# Installation ::note You are reading the `v2` documentation compatible with **Nuxt 3.1+** . :br Checkout [v0.image.nuxtjs.org](https://v0.image.nuxtjs.org/getting-started/installation){rel=""nofollow""} for **Nuxt 2** compatible version. ( [Announcement](https://github.com/nuxt/image/discussions/548){rel=""nofollow""} ). :: ## Automatic Installation To get started, add `@nuxt/image` to your project: ```bash npx nuxt module add image ``` ## Manual Installation Add `@nuxt/image` dependency to your project: ::code-group ```bash [npm] npm i @nuxt/image ``` ```bash [yarn] yarn add @nuxt/image ``` ```bash [pnpm] pnpm add @nuxt/image ``` ```bash [bun] bun add @nuxt/image ``` :: Then, add it to the `modules` in your `nuxt.config`: ```ts [nuxt.config.ts] export default defineNuxtConfig({ modules: [ '@nuxt/image' ] }) ``` ## Sharp Cross-Platform Installation The default [IPX](https://image.nuxt.com/providers/ipx) provider uses [sharp](https://sharp.pixelplumbing.com){rel=""nofollow""} for image processing. At install time, your package manager downloads prebuilt sharp binaries **only for your current OS and CPU architecture**. This means if you build on macOS or Windows and deploy to a Linux server (or build on x64 and deploy to ARM64), the required sharp binaries might be missing, resulting in errors like: ```text [500] [IPX_ERROR] Could not load the "sharp" module using the linux-x64 runtime ``` To fix this, configure your package manager to install sharp binaries for **all target platforms**, e.g.: ::code-group ```json [pnpm (package.json)] { "pnpm": { "supportedArchitectures": { "os": ["current", "linux"], "cpu": ["current", "x64", "arm64"] } } } ``` ```yaml [yarn (.yarnrc.yml, v3+ only)] supportedArchitectures: os: - current - linux cpu: - current - x64 - arm64 ``` ```bash [npm] npm install --cpu=x64 --os=linux sharp npm install --cpu=arm64 --os=linux sharp ``` :: After updating the configuration, reinstall dependencies to download the additional platform binaries. For more details, see the [sharp cross-platform documentation](https://sharp.pixelplumbing.com/install/#cross-platform){rel=""nofollow""}. ## Configuration Add an `image` section in your `nuxt.config`: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { // Options } }) ``` ::tip Checkout the [image configuration](https://image.nuxt.com/get-started/configuration) for all available options and features to customize. :: ## Edge Channel After each commit is merged into the `main` branch of `@nuxt/image` and **passing all tests**, we trigger an automated npm release using GitHub Actions publishing a [`@nuxt/image-nightly`](https://npmjs.com/package/@nuxt/image-nightly){rel=""nofollow""} package. You can opt in to use this release channel and avoid waiting for the next release and helping the module by beta testing changes. The build and publishing method and quality of edge releases are the same as stable ones. The only difference is that you should often check the [GitHub repository](https://github.com/nuxt/image){rel=""nofollow""} for updates. There is a slight chance of regressions not being caught during the review process and by the automated tests. Therefore, we internally use this channel to double-check everything before each release. ### Opting into the edge channel Update `@nuxt/image` dependency inside `package.json`: ```diff [package.json] { "devDependencies": { - "@nuxt/image": "^1.0.0" + "@nuxt/image": "npm:@nuxt/image-nightly@latest" } } ``` Remove lockfile (`package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`) and reinstall dependencies. ### Opting out from the edge channel Update `@nuxt/image` dependency inside `package.json`: ```diff [package.json] { "devDependencies": { - "@nuxt/image": "npm:@nuxt/image-nightly@latest" + "@nuxt/image": "^1.0.0" } } ``` Remove lockfile (`package-lock.json`, `yarn.lock`, or `pnpm-lock.yaml`) and reinstall dependencies. ## Troubleshooting If an error occurs during installation: - Ensure using LTS version of NodeJS ([NodeJS Download page](https://nodejs.org/en/download){rel=""nofollow""}) - Try to upgrade to latest versions: ::code-group ```bash [npm] npm up @nuxt/image ``` ```bash [yarn] yarn upgrade @nuxt/image ``` ```bash [pnpm] pnpm up @nuxt/image ``` ```bash [bun] bun update @nuxt/image ``` :: - Try recreating lockfile: ::div ```bash npx nuxt upgrade --force ``` :: - If none of the above worked, please [open an issue](https://github.com/nuxt/image/issues){rel=""nofollow""} and include error trace, OS, Node version and the package manager used for installing. # Configuration To configure the image module and customize its behavior, you can use the `image` property in your `nuxt.config`: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { // Options } }) ``` ## `inject` By default Nuxt Image v1 adopts a composable approach. If you do not use the components no additional code will be added to your bundle. But if you wish to globally initialize an `$img` helper that will be available throughout your application, you can do so. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { inject: true } }) ``` ## `quality` The quality for the generated image(s). You can also override this option at the component level by using the [`quality` prop](https://image.nuxt.com/usage/nuxt-img#quality). ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { quality: 80 } }) ``` ## `format` Default: `['webp']` You can use this option to configure the default format for your images used by ``. The available formats are `webp`, `avif`, `jpeg`, `jpg`, `png`, and `gif`. The order of the formats is important, as the first format that is supported by the browser will be used. You can pass multiple values like `['avif', 'webp']`. You can also override this option at the component level by using the [`format` prop](https://image.nuxt.com/usage/nuxt-picture#format). ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { format: ['webp'] } }) ``` ## `screens` List of predefined screen sizes. These sizes will be used to generate resized and optimized versions of an image (for example, with the [`sizes`](https://image.nuxt.com/usage/nuxt-img#sizes) modifier). ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { // The screen sizes predefined by `@nuxt/image`: screens: { 'sm': 640, 'md': 768, 'lg': 1024, 'xl': 1280, '2xl': 1536 } } }) ``` ::note By default, we share the same naming and sizes as [Tailwind CSS](https://tailwindcss.com/docs/responsive-design){rel=""nofollow""} . If you need a list of screen sizes matching a different framework, check out [VueUse breakpoint presets](https://vueuse.org/core/useBreakpoints/#presets){rel=""nofollow""} . :: ## `domains` To enable image optimization on an external website, specify which domains are allowed to be optimized. This option will be used to detect whether a remote image should be optimized or not. This is needed to ensure that external URLs can't be abused. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { domains: ['nuxtjs.org'] } }) ``` ## `presets` Presets are collections of pre-defined configurations for your projects. Presets will help you to unify images all over your project. ::code-group ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { presets: { avatar: { modifiers: { format: 'jpg', width: 50, height: 50 } } } } }) ``` ```vue [index.vue] ``` :: ## `providers` In order to create and use a [custom provider](https://image.nuxt.com/advanced/custom-provider), you need to use the `providers` option and define your custom providers. ::code-group ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { providers: { random: { provider: '~/providers/random', options: {} } } } }) ``` ```vue [index.vue] ``` :: ## `provider` Default: `ipx` (or `ipxStatic` if used with a static nitro preset, such as if you are running `nuxt generate`) We can specify default provider to be used when not specified in component or when calling `$img`. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { provider: 'twicpics', twicpics: { baseURL: 'https://nuxt-demo.twic.pics' } } }) ``` ### `modifiers` You can set default modifiers for the selected provider. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { provider: 'cloudinary', cloudinary: { baseURL: 'https://res.cloudinary.com//image/fetch', modifiers: { effect: 'sharpen:100', quality: 'auto:best' } } } }) ``` ## `densities` Default: `[1, 2]` Specify a value to work with `devicePixelRatio` > 1 (these are devices with retina display and others). You must specify for which `devicePixelRatio` values you want to adapt images. You can [read more about `devicePixelRatio` on MDN](https://developer.mozilla.org/en-US/docs/Web/API/Window/devicePixelRatio){rel=""nofollow""}. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { densities: [1, 2, 3] } }) ``` ## `dir` Default: `public` This option allows you to specify the location of the source images when using the `ipx` or `ipxStatic` provider. For example you might want the source images in `assets/images` directory rather than the default `public` directory so the source images don't get copied into `dist` and deployed: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { dir: 'assets/images' } }) ``` **Notes:** - For `ipxStatic` provider, if images weren't crawled during generation (unreachable modals, pages or dynamic runtime size), changing `dir` from `public` causes 404 errors. - For `ipx` provider, make sure to deploy customized `dir` as well. - For some providers (like vercel), using a directory other than `public/` for assets is not supported since resizing happens at runtime (instead of build/generate time) and source fetched from the `public/` directory (deployment URL) ## `alias` This option allows you to specify aliases for `src`. When using the default ipx provider, URL aliases are shortened on the server-side. This is especially useful for optimizing external URLs and not including them in HTML. When using other providers, aliases are resolved in runtime and included in HTML. (only the usage is simplified) **Example:** ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { domains: [ 'images.unsplash.com' ], alias: { unsplash: 'https://images.unsplash.com' } } }) ``` **Before** using alias: ```vue ``` Generates: ```html ``` **After** using alias: ```vue ``` Generates: ```html ``` Both usage and output are simplified! # Providers ## Introduction to Providers Providers are integrations between Nuxt Image and third-party image transformation services. Each provider is responsible for generating correct URLs for that image transformation service. Nuxt Image can be configured to work with any external image transformation service. Checkout the sidebar for a list of preconfigured providers. If you are looking for a specific provider that is not already supported, you can [create your own provider](https://image.nuxt.com/advanced/custom-provider). Nuxt Image will automatically optimize `` and `` sources and accepts all [options](https://image.nuxt.com/get-started/configuration) for specified targets, except for modifiers that are specific to other providers. ## Default Provider The default optimizer and provider for Nuxt Image is [ipx](https://image.nuxt.com/providers/ipx). Either option can be used without any configuration. ### Local Images Images should be stored in the `public/` directory of your project. For example, when rendering a ``, your PNG file should be placed in the `public/` directory under the path `public/nuxt-icon.png`. For more information, you can learn more about the [public directory](https://nuxt.com/docs/guide/directory-structure/public){rel=""nofollow""}. ::note Images stored in the `assets/` directory are **not** processed with Nuxt Image because those images are managed by your bundler (such as Vite or webpack). :: ### Remote Images Using the default provider, you can also optimize external URLs. For this, you need to add them to the [`domains`](https://image.nuxt.com/get-started/configuration#domains) option. You can also add domains for remote images by setting the `NUXT_IMAGE_DOMAINS` environment variable to a comma-separated list of domains. ```bash NUXT_IMAGE_DOMAINS="example.com,yourdomain.com" ``` ### Environment Detection You can set the default provider using the `NUXT_IMAGE_PROVIDER` environment variable. Providers detected automatically: - [AWS Amplify](https://image.nuxt.com/providers/aws-amplify) - [Netlify](https://image.nuxt.com/providers/netlify) - [Vercel](https://image.nuxt.com/providers/vercel) ### Custom Provider It is possible to define your own provider, learn more about [how to create a custom provider](https://image.nuxt.com/advanced/custom-provider). # Contributing ::warning It is highly recommended to read the [Nuxt contribution guide](https://nuxt.com/docs/community/contribution){rel=""nofollow""} before making any contributions. :: ## How to contribute? - Clone [nuxt/image](https://github.com/nuxt/image){rel=""nofollow""} repository - Enable Corepack using `corepack enable` - Install dependencies using `pnpm install` - Run `pnpm dev:prepare` to generate type stubs. ### Nuxt Image - Use `pnpm dev` to start the [playground](https://github.com/nuxt/image/tree/main/playground){rel=""nofollow""} in development mode. - Apply your changes - Add tests into the [test/](https://github.com/nuxt/image/tree/main/test){rel=""nofollow""} directory and run `pnpm test` to make sure they pass. - Check the code style with `pnpm lint` - Before creating a PR, make sure to run `pnpm build` and that no errors are reported. ### Documentation - Use `pnpm docs:dev` to start the [documentation](https://github.com/nuxt/image/tree/main/docs){rel=""nofollow""} in development mode. - Open {rel=""nofollow""} to view it in the browser. - Update the content of the documentation in the [docs/content/](https://github.com/nuxt/image/tree/main/docs/content){rel=""nofollow""} directory. # Migration to v2 Nuxt Image v2 brings improved performance, enhanced TypeScript support, and a better developer experience. Most apps should be able to upgrade with minimal changes. ## Update dependencies Update `@nuxt/image` to v2: ::code-group{sync="pm"} ```bash [pnpm] pnpm add @nuxt/image ``` ```bash [yarn] yarn add @nuxt/image ``` ```bash [npm] npm install @nuxt/image ``` ```bash [bun] bun add @nuxt/image ``` ```bash [deno] deno add npm:@nuxt/image ``` :: ## Check your Nuxt version Nuxt Image v2 requires at least **Nuxt 3.1**. Check your current version: ```bash npm list nuxt ``` If you're on Nuxt 3.0.x, upgrade first: ```bash npx nuxt upgrade --channel v3 ``` ::tip Nuxt Image v2 is fully compatible with Nuxt 4. See the [Nuxt 4 migration guide](https://nuxt.com/docs/getting-started/upgrade#nuxt-4){rel=""nofollow""} if you're ready to upgrade. :: ## Update screen sizes The `xs` and `xxl` breakpoints have been removed to align with Tailwind CSS defaults. Search for usage in your project: ```bash grep -r "sizes.*xs:" --include="*.vue" grep -r "sizes.*xxl:" --include="*.vue" ``` **If you are using these screen sizes**, you can either replace `xs` with `sm` and `xxl` with `2xl`: ```diff ``` ... or you can add them back in your config: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { screens: { xs: 320, xxl: 1536 } } }) ``` ## Update custom providers If you have custom image providers, update them to use `defineProvider`. **Before (v1):** ```ts [providers/my-provider.ts] export const getImage = (src, { modifiers }) => { // ... return { url } } ``` **After (v2):** ```ts [providers/my-provider.ts] import { defineProvider } from '@nuxt/image/runtime' export default defineProvider({ getImage(src, { modifiers }) { // ... return { url } } }) ``` ### Add modifier types (optional) Add types for custom modifiers: ```ts [providers/my-provider.ts] import { defineProvider } from '@nuxt/image/runtime' import type { ImageModifiers } from '@nuxt/image' interface MyProviderModifiers extends ImageModifiers { watermark?: 'logo' | 'text' | 'none' rotate?: number } export default defineProvider({ getImage(src, { modifiers }) { // ... return { url } } }) ``` Modifiers will now be typed within your provider, and also when it is used within `` and ``. ### Update formatter Within `createOperationsGenerator`, if you used `joinWith` for parameter formatting, but didn't use `formatter`, you will now need to add a custom formatter. ```ts [providers/my-provider.ts] import { createOperationsGenerator, defineProvider } from '@nuxt/image/runtime' const operationsGenerator = createOperationsGenerator({ keyMap: { width: 'w', height: 'h' }, joinWith: '&', formatter: (key, value) => `${key}=${encodeURIComponent(value)}` }) export default defineProvider({ getImage(src, { modifiers, baseURL = '/' }) { const operations = operationsGenerator(modifiers) return { url: `${baseURL}${src}?${operations}` } } }) ``` # `` is a drop-in replacement for the native `` tag. - Uses built-in provider to optimize local and remote images - Converts `src` to provider optimized URLs - Automatically resizes images based on `width` and `height` - Generates responsive sizes when providing `sizes` option - Supports native lazy loading as well as other `` attributes ## Usage `` outputs a native `img` tag directly (without any wrapper around it). Use it like you would use the `` tag: ```vue ``` Will result in: ```html ``` ::note With [default provider](https://image.nuxt.com/get-started/providers) , you should put `/nuxt-icon.png` inside `public/` directory for Nuxt 3 make the above example work. :: ## Props ### `custom` The `custom` prop determines whether `` should render as a simple `` element or only serve as a provider for custom rendering. When set to `true`, it disables the default rendering behavior, allowing full control over how the image is displayed. This is useful for implementing custom functionalities, such as placeholders. When using the `custom` prop, `` passes necessary data and attributes to its default slot. You can access the following values via the `v-slot` directive: - `imgAttrs`: Attributes for the `` element (e.g., `alt`, `width`, `height`, `srcset`, `sizes`). - `src`: The computed image source URL. - `isLoaded`: A boolean indicating whether the image has been loaded. #### Example Usage ```vue placeholder ``` This approach ensures flexibility for custom rendering scenarios, while `` continues to handle image optimization and data provisioning behind the scenes. ### `src` Path to image file `src` should be in the form of an absolute path for static images in `public/` directory. Otherwise path that is expected by provider that starts with `/` or a URL. ```vue ``` For image optimization when using external URLs in `src`, we need to whitelist them using [`domains`](https://image.nuxt.com/get-started/configuration#domains) option. ### `width` / `height` Specify width/height of the image. - Use desired width/height for static sized images like icons or avatars - Use original image width/height for responsive images (when using [`sizes`](https://image.nuxt.com/#sizes)) ### `alt` Although Nuxt Image does not apply any special handling, it's worth mentioning the `alt` attribute. It is a [native](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/alt){rel=""nofollow""} global attribute that specifies an alternate text for an image, if the image cannot be displayed. It *should always* be provided. - The text should describe the image if the image contains information - The text should explain where the link goes if the image is inside an `` element - Use `alt=""` if the image is only for decoration ```vue ``` ### `sizes` Specify responsive sizes. This is a space-separated list of screen size/width pairs. You can [see a list of the defined screen sizes here](https://image.nuxt.com/get-started/configuration#screens). By default Nuxt generates *responsive-first* sizing. - If you omit a screen size prefix (like `sm:`) then this size is the 'default' size of the image. Otherwise, Nuxt will pick the smallest size as the default size of the image. - This default size is used up until the next specified screen width, and so on. Each specified size pair applies *up* - so `md:400px` means that the image will be sized `400px` on `md` screens and up. **Example:** ```vue ``` ### `densities` The `densities` prop serves high-resolution images for Retina/HiDPI screens. Nuxt Image generates multiple versions at different pixel densities and creates the appropriate `srcset`. When you specify densities, Nuxt Image multiplies your base dimensions by each density value to generate the corresponding image sizes. **Example:** ```vue ``` Will result in: ```html ``` ### `placeholder` Display a placeholder image before the actual image is fully loaded. You can also use the [custom prop](https://image.nuxt.com/usage/nuxt-img#custom) to make any placeholder you want. The placeholder prop can be either a string, a boolean, a number, or an array. The usage is shown below for each case. ```vue ``` You can also leverage [`useImage()`](https://image.nuxt.com/usage/use-image) to generate a placeholder image based on the original image, can be useful if the source is an SVG or you want better control on the modifiers: ```vue ``` ### `placeholder-class` When using a placeholder, you can use `placeholder-class` to apply a class to the original underlying `` element (while the placeholder is being rendered). ```vue ``` ::tip If you need to apply some CSS to only the *loaded* image you can do so with something like: ```css img:not(.my-placeholder-class) { /* styles here */ } ``` :: ### `provider` Use other provider instead of default [provider option](https://image.nuxt.com/get-started/configuration#provider) specified in `nuxt.config` **Example:** ::code-group ```vue [index.vue] ``` ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { cloudinary: { baseURL: 'https://res.cloudinary.com/nuxt/image/upload' } } }) ``` :: ### `preset` Presets are predefined sets of image modifiers that can be used create unified form of images in your projects. ::note We can define presets using [presets options](https://image.nuxt.com/get-started/configuration#presets) in `nuxt.config` :: ::code-group ```vue [index.vue] ``` ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { presets: { cover: { modifiers: { fit: 'cover', format: 'jpg', width: 300, height: 300 } } } } }) ``` :: ### `format` In case you want to serve images in a specific format, use this prop. ```vue ``` Available formats are `webp`, `avif`, `jpeg`, `jpg`, `png`, `gif` and `svg`. If the format is not specified, it will respect the default image format. ### `quality` The quality for the generated image(s). ```vue ``` ### `fit` The `fit` property specifies the size of the images. There are five standard values you can use with this property. - `cover`: (default) Preserving aspect ratio, ensure the image covers both provided dimensions by cropping/clipping to fit - `contain`: Preserving aspect ratio, contain within both provided dimensions using 'letterboxing' where necessary. - `fill`: Ignore the aspect ratio of the input and stretch to both provided dimensions. - `inside`: Preserving aspect ratio, resize the image to be as large as possible while ensuring its dimensions are less than or equal to both those specified. - `outside`: Preserving aspect ratio, resize the image to be as small as possible while ensuring its dimensions are greater than or equal to both those specified. ```vue ``` ::note Some providers support other values. :: ### `modifiers` In addition to the standard modifiers, each provider might have its own additional modifiers. Because these modifiers depend on the provider, refer to its documentation to know what can be used. Using the `modifiers` prop lets you use any of these transformations. **Example:** ```vue ``` ### `preload` In case you want to preload the image, use this prop. This will place a corresponding `link` tag in the page's head. ```vue ``` Passing an object to the preload prop lets you define the `fetchPriority` property. Note that the JavaScript property `fetchPriority` maps to the [`fetchpriority`](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/fetchpriority){rel=""nofollow""} HTML attribute in the preload link tag. Accepted values are `auto`, `high`, or `low`. ```vue ``` ### `loading` This is a [native](https://developer.mozilla.org/en-US/docs/Web/API/HTMLImageElement/loading){rel=""nofollow""} attribute that provides a hint to the browser on how to handle the loading of an image which is outside the viewport. It is [supported](https://caniuse.com/loading-lazy-attr){rel=""nofollow""} by the latest version of all major browsers since March 2022. Set `loading="lazy"` to defer loading of an image until it appears in the viewport. ```vue ``` ### `nonce` This is a [native](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce){rel=""nofollow""} global attribute that defines a cryptographic nonce (number used once) that can be used by Content Security Policy to determine whether or not a given fetch will be allowed to proceed for a given element. Providing a nonce allows you to avoid using the CSP `unsafe-inline` directive, which would allowlist *all* inline script or styles. ```vue ``` ## Events Native events emitted by the `` element contained by `` and `` components are re-emitted and can be listened to. **Example:** Listen to the native `onLoad` event from `` ```vue ``` # `` is a drop-in replacement for the native `` tag. Usage of `` is almost identical to [``](https://image.nuxt.com/nuxt-img) but also allows serving modern formats like `webp` when possible. Learn more about the [`` tag on MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture){rel=""nofollow""}. ::warning Unlike the native [`` element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture){rel=""nofollow""} , `` currently doesn't support using multiple image sources. See [#309](https://github.com/nuxt/image/issues/309){rel=""nofollow""} for more info. :: ## Props ::tip See props supported by [``](https://image.nuxt.com/usage/nuxt-img#props) :: ### `format` Format on pictures can be used to serve images in multiple formats. A legacy format will be generated automatically. So in the example below avif, webp and png would be generated. They will be added in the same order they are added to the format attribute. ```vue ``` Available formats are `webp`, `avif`, `jpeg`, `jpg`, `png`, and `gif`. If the format is not specified, it will respect the default image format. ### `legacyFormat` Format used for fallback. Default is conditional: - If original format supports transparency (`png`, `webp`, and `gif`), `png` is used for fallback - Otherwise `jpeg` is used for fallback ### `imgAttrs` Allows you to set additional HTML-attributes on the `img` element. **Example:** ```vue ``` # useImage() Sometimes you might need to use a generated image URL directly with applied transformations instead of the `` and `` components. This is where `useImage()` comes in (and the helper function it returns, which you will often see referenced directly as `$img` or `img`). ## Usage ```js const img = useImage() img(src, modifiers, options) ``` **Example:** Generate image URL for `backgroundImage` style. ```js const img = useImage() const backgroundStyles = computed(() => { const imgUrl = img('https://github.com/nuxt.png', { width: 100 }) return { backgroundImage: `url('${imgUrl}')` } }) ``` ### `img.getSizes` ```js const img = useImage() img.getSizes(src, { sizes, modifiers }) ``` ::warning Unstable: `getSizes` API might change or be removed. :: **Parameters:** - `src`: (string) Source to original image id - `sizes`: (string) List of responsive image sizes ({breakpoint}:{size}{unit}) - `modifiers`: (object) Modifiers passed to provider for resizing and optimizing - `width`: resize to the specified width (in pixels) - `height`: resize to specified height (in pixels) - `quality`: Change image quality (0 to 100) - `format`: Change the image format - (any other custom provider modifier) - `options`: (object) - `provider`: (string) Provider name other than default (see [providers](https://image.nuxt.com/get-started/configuration#providers)) - `preset`: Use a [preset](https://image.nuxt.com/get-started/configuration#presets) **Example:** Responsive srcset with Vuetify `v-img` ```html ``` # Aliyun Integration between [Aliyun CDN](https://cdn.console.aliyun.com){rel=""nofollow""} and the image module. To use this provider you just need to specify the base URL (zone) of your service: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { aliyun: { baseURL: 'https://that-test.site' } } }) ``` **Example:** ```vue ``` ## Options ### `baseURL` Default: `/` Your deployment's domain (zone). ## Modifiers **Example:** ```js { resize: { fw: 900, fh: 200 }, rotate: 180, bright: 50, ... } ``` For more modifiers configuration items, see [Aliyun CDN docs](https://help.aliyun.com/zh/cdn/user-guide/image-editing){rel=""nofollow""}. # AWS Amplify Integration between [AWS Amplify Hosting](https://aws.amazon.com/amplify){rel=""nofollow""} and the image module. This provider will be enabled by default in AWS Amplify deployments. ::alert{type="warning"} This is an experimental preset and will be available soon! 🚀 :: ## Domains To use external URLs (images not in `public/` directory), hostnames should be whitelisted. **Example:** ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { domains: ['avatars0.githubusercontent.com'] } }) ``` ## Sizes Specify any custom `width` property you use in ``, `` and `$img`. If a width is not defined, image will fallback to the next bigger width. **Example:** ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { screens: { icon: 40, avatar: 24 } } }) ``` ## Modifiers All the default modifiers from [AWS's documentation](https://docs.aws.amazon.com/amplify/latest/userguide/integrate-image-optimization-framework.html#uri-request-parameters){rel=""nofollow""} are available. ```vue ``` ## Options ### `formats` - Type: **String []** (optional) Specify the image format allow list for optimization. By default, the provider set the following formats: `['image/jpeg', 'image/png', 'image/webp', 'image/avif']`. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { awsAmplify: { formats: ['image/jpeg', 'image/png', 'image/webp'] } } }) ``` # Builder.io Integration between [Builder.io Image API](https://www.builder.io/c/docs/image-api){rel=""nofollow""} and Nuxt Image. The Builder.io Image API provides optimized image transformations for images uploaded to Builder.io. ## Modifiers The Builder.io provider supports the following modifiers: - `width` - `height` - `format` - `quality` - `fit` - `position` ### Format The `format` modifier is supported with the following values: - `webp` - `jpg` - `jpeg` - `png` - `gif` - `original` ```vue ``` ### Quality The `quality` modifier is supported. Values range from 1 (worst quality, smallest file size) to 100 (best quality, largest file size). Default is 85. ```vue ``` ### Fit The `fit` modifier determines how the image should fit within the specified dimensions. Valid values are: - `cover` - Cover the entire area (default) - `contain` - Fit within the area while maintaining aspect ratio - `fill` - Fill the area, potentially distorting the image - `inside` - Fit inside the area while maintaining aspect ratio - `outside` - Fit outside the area while maintaining aspect ratio **Note:** The `fit` parameter only has an effect if `format` is set to `webp`. ```vue ``` ### Position The `position` modifier determines the anchor point for cropping when `fit` is used. Valid values are: - `top` - `right top` - `right` - `right bottom` - `bottom` - `left bottom` - `left` - `left top` - `center` (default) **Note:** The `position` parameter only has an effect if `format` is set to `webp`. ```vue ``` ## Usage To use this provider, pass the image URL from Builder.io to the `src` prop: ```vue ``` For more information about the Builder.io Image API, see the [official documentation](https://www.builder.io/c/docs/image-api){rel=""nofollow""}. # Bunny Integration between [Bunny](https://bunny.net){rel=""nofollow""} and the image module. To use this provider you just need to specify the base URL of your project. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { bunny: { baseURL: '' } } }) ``` ## Modifiers All the default modifiers from [Bunny's documentation](https://docs.bunny.net/docs/stream-image-processing){rel=""nofollow""} are available. ```vue ``` # Caisy Integration between [Caisy](https://caisy.io){rel=""nofollow""} and the image module. To use this provider you just need to specify the base URL of your project. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { caisy: {} } }) ``` ## Modifiers All the default modifiers from [Caisy's documentation](https://caisy.io/developer/docs/libraries/rendering-images){rel=""nofollow""} are available. ```vue ``` # Cloudflare Integration between [Cloudflare](https://developers.cloudflare.com/images){rel=""nofollow""} and the image module. ::warning Before using this provider, make sure to enable **Image Transformations** for your domain in the Cloudflare dashboard at `Images > Transformations` . If you plan to use images from external domains, also enable 'Resize Image from Any Origin'. :: To use this provider you just need to specify the base URL (zone) of your service: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { cloudflare: { baseURL: 'https://that-test.site' } } }) ``` **Example:** ```vue ``` ## Options ### `baseURL` Default: `/` Your deployment's domain (zone). **Note:** `/cdn-cgi/image/` will be automatically appended for generating URLs. # Cloudflare Images Integration between [Cloudflare Images](https://developers.cloudflare.com/images/){rel=""nofollow""} and the image module. ::note This provider is for **Cloudflare Images** — the image hosting and delivery product where you upload images to Cloudflare and reference them by image ID. If you want to transform images on your own domain using **Cloudflare Image Transformations** (via `/cdn-cgi/image/` ), use the [`cloudflare` provider](https://image.nuxt.com/providers/cloudflare) instead. :: ## Setup You need your **account hash**, which you can find in the Cloudflare dashboard under **Images > Overview > Developer Resources**. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { cloudflareimages: { accountHash: 'YOUR_ACCOUNT_HASH' } } }) ``` Images are referenced by their **image ID** (not a URL path): ```vue ``` ## Options ### `accountHash` **Required.** Your Cloudflare Images account hash. ### `baseURL` Default: `https://imagedelivery.net/` The base URL for image delivery. You can change this if you are serving images through a [custom domain](https://developers.cloudflare.com/images/manage-images/serve-images/serve-from-custom-domains/){rel=""nofollow""}. ## Variants vs. flexible transformations Cloudflare Images supports two ways of serving images: 1. **Named variants** — Predefined sizes [configured in the Cloudflare dashboard](https://developers.cloudflare.com/images/manage-images/create-variants/){rel=""nofollow""} (e.g. `public`, `thumbnail`). Use the `variant` modifier. 2. **Flexible variants** — On-the-fly [transformations](https://developers.cloudflare.com/images/transform-images/transform-via-url/){rel=""nofollow""} using width, height, fit, etc. This must be enabled in your Cloudflare Images dashboard. When you pass a `variant` modifier or no image modifiers at all, the provider uses the variant URL format. Otherwise, it uses flexible variant transformations. ```vue ``` ## Modifiers On top of the [standard modifiers](https://image.nuxt.com/usage/nuxt-img#modifiers), the following Cloudflare Images-specific modifiers are supported when using flexible variants: | Modifier | Description | | ------------- | --------------------------------------------------------------------------------------- | | `variant` | Named variant to use (e.g. `public`, `thumbnail`). Takes priority over other modifiers. | | `dpr` | Device pixel ratio multiplier. | | `gravity` | Cropping gravity: `auto`, `face`, `left`, `right`, `top`, `bottom`. | | `sharpen` | Sharpen amount (0-10). | | `rotate` | Rotation angle: `90`, `180`, or `270`. | | `brightness` | Brightness adjustment. | | `contrast` | Contrast adjustment. | | `gamma` | Gamma adjustment. | | `saturation` | Saturation adjustment. | | `anim` | `'true'` or `'false'` — whether to preserve animation frames. | | `metadata` | Metadata handling: `copyright`, `keep`, or `none`. | | `compression` | Set to `'fast'` for faster compression. | | `flip` | Flip image: `h` (horizontal), `v` (vertical), or `hv` (both). | | `zoom` | Zoom factor for use with `gravity: 'face'` (0-1). | ### `fit` | Value | Cloudflare behavior | | --------- | --------------------------------------------------- | | `cover` | Image covers the box, cropping if necessary. | | `contain` | Image fits inside the box, preserving aspect ratio. | | `fill` | Pads the image to fill the box. | | `outside` | Crops the image to fill the box. | | `inside` | Scales down to fit, never enlarging. | # Cloudimage Integration between [Cloudimage](https://www.cloudimage.io/en/home){rel=""nofollow""} and the image module. To use this provider you need to specify either your Cloudimage `token` (with optional `apiVersion`) or a full `cdnURL`. The `baseURL` of your image storage is optional and is only used when the passed `src` is not an absolute URL. When using absolute URLs, the provider will use the `cdnURL` directly without prepending the `baseURL`. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { cloudimage: { token: 'your_cloudimage_token', baseURL: 'origin_image_url' // or alias (optional) } } }) ``` ## Options ### `token` - Type: **String** (required) Your Cloudimage customer token. [Register](https://www.cloudimage.io/en/register_page){rel=""nofollow""} for a Cloudimage account to get one. Registration takes less than a minute and is totally free. ### `baseURL` - Type: **String** (optional) Your origin image URL or storage alias that allows to shorten your origin image URLs. If not provided, the provider will fall back to base App URL for relative URLs, or use the `cdnURL` directly for absolute URLs. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { cloudimage: { token: 'demo', baseURL: 'sample.li' } } }) ``` These formats all work as well: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { cloudimage: { token: 'demo', baseURL: 'sample.li/images', baseURL: 'https://sample.li/images', baseURL: '_sl_' // alias defined in your Cloudimage storage settings } } }) ``` ### `apiVersion` - Type: **String** - Default: `empty string` Allow using a specific version of the API. ::note For tokens created before **20.10.2021** , `apiVersion` needs to be set to `v7` . :: Here's an official demo config. `demo` is an old token hence `apiVersion` needs to be defined as well. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { cloudimage: { token: 'demo', baseURL: 'sample.li', apiVersion: 'v7' } } }) ``` ### `cdnURL` - Type: **String** - Default: `https://{token}.cloudimg.io/{apiVersion}` Replaces the dynamically built URL. Useful when you prefer not to provide a `token` or need a custom CDN hostname. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { cloudimage: { cdnURL: 'https://demo.cloudimg.io/v7' } } }) ``` When only `cdnURL` is provided and `baseURL` is omitted, relative sources will fallback to the website's base URL, for example `src: '/test.png'` becomes `https://demo.cloudimg.io/v7/{website-base-url}/test.png`. When using absolute URLs with `cdnURL`, the provider will use the CDN URL directly without prepending any base URL. ### Examples **Using absolute URLs with cdnURL:** ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { cloudimage: { cdnURL: 'https://demo.cloudimg.io/v7' } } }) ``` With this configuration: - `src: 'https://example.com/image.jpg'` becomes `https://demo.cloudimg.io/v7/https://example.com/image.jpg` - `src: '/local/image.jpg'` becomes `https://demo.cloudimg.io/v7/{website-base-url}/local/image.jpg` **Using token with automatic baseURL fallback:** ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { cloudimage: { token: 'demo', apiVersion: 'v7' // baseURL will automatically fall back to the website's base URL } } }) ``` ## Cloudimage Modifiers Beside the [standard modifiers](https://image.nuxt.com/usage/nuxt-img#modifiers), also you can pass Cloudimage-specific [Cloudimage-specific transformation](https://docs.cloudimage.io/go/cloudimage-documentation-v7/en/introduction){rel=""nofollow""} params to `modifiers` prop. ## Cloudimage `fit` Values Beside the [standard values for `fit` property](https://image.nuxt.com/usage/nuxt-img#fit) of Nuxt image and Nuxt picture, Cloudimage offers the following for extra resizing params: - `crop` - Crops the image to specified dimensions (width and height) and keeps proportions. - `face` - Crops the image automatically keeping the most prominent face. - `fit` - Resizes the image to fit into a specified width and height box, adds padding (image or solid color) to keep proportions. - `cropfit` - Sets crop or fit resize mode depending on the origin and the desired dimensions. - `bound` - Resizes to a given width and height box and keeps proportions. Similar to fit but without adding padding. - `boundmin` - Resizes an image while bounding the smaller dimension to the desired width or height while keeping proportions. # Cloudinary Integration between [Cloudinary](https://cloudinary.com){rel=""nofollow""} and the image module. ::tip If you are looking for more advanced Cloudinary usage or prebuilt components like VideoPlayer, OgImage or ProductGallery, check out Cloudinary module for Nuxt by visiting module [documentation](https://cloudinary.nuxtjs.org){rel=""nofollow""} or GitHub [repository](https://github.com/nuxt-modules/cloudinary){rel=""nofollow""} :: To use this provider you just need to specify the base URL of your project in Cloudinary. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { cloudinary: { baseURL: 'https://res.cloudinary.com//image/upload' } } }) ``` ## Remote Images To handle remote image data, you can either use [fetch](https://cloudinary.com/documentation/fetch_remote_images#remote_image_fetch_url){rel=""nofollow""} or [upload](https://cloudinary.com/documentation/fetch_remote_images#auto_upload_remote_resources){rel=""nofollow""}. Consult the [Cloudinary documentation](https://cloudinary.com/documentation/fetch_remote_images#comparing_fetch_to_auto_upload){rel=""nofollow""} for the difference between the two. ### Fetch ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { cloudinary: { baseURL: 'https://res.cloudinary.com//image/fetch' } } }) ``` ```vue ``` Note: You will need to configure your 'Allowed fetch domains' to do the above. ### Upload ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { cloudinary: { baseURL: 'https://res.cloudinary.com//image/upload/' } } }) ``` ```vue ``` Note: You will need to configure your 'Auto upload mapping' to do the above. ## Cloudinary `fit` values Beside the [standard values for `fit` property](https://image.nuxt.com/usage/nuxt-img#fit) of Nuxt image and Nuxt picture, Cloudinary offers the following for extra resizing experience: - `minCover` - Same like `cover` but only resizing if the original image is **smaller** than the given minimum (width and height). - `minInside` - Same as the `inside` mode but only if the original image is **smaller** than the given minimum (width and height). - `coverLimit` - Same as the `cover` mode but only if the original image is **larger** than the given limit (width and height) - `thumbnail`- Generate a thumbnail using face detection. - `cropping` - Used to extract a given width & height out of the original image. The original proportions are retained. Check out [Cloudinary resize mode Documentation](https://cloudinary.com/documentation/image_transformation_reference#crop_parameter){rel=""nofollow""} for more details. ## Cloudinary Modifiers Beside the [standard modifiers](https://image.nuxt.com/usage/nuxt-img#modifiers), you can also pass the following Cloudinary-specific transformation params to `modifiers` prop. ::note The Cloudinary provider automatically enables [automatic format selection](https://cloudinary.com/documentation/image_transformations#f_auto){rel=""nofollow""} and [automatic quality selection](https://cloudinary.com/documentation/image_optimization#automatic_quality_selection_q_auto){rel=""nofollow""} for best performance. :: ### `rotate` Accepted values: - Any degree number, or - `auto_right` | `auto_left` | `ignore` | `vflip` | `hflip` To rotate or flip a given asset by certain degrees, or automatically based on orientation. ### `roundCorner` Round the specified corners of the desired image. If pass only a number or `max` (all corners will be applied). The syntax for other use cases is as below: - Using 2 values: `top_left_bottom_right_radius:top_right_bottom_left_radius`(Example: `20:40`) - Using 3 values: `top_left:top_right_bottom_left:bottom_right` (Example: `20:30:40`) - Using 4 values: `top_left:top_right:bottom_left:bottom_right` (Example: `20:0:40:40`) ```vue ``` ### `gravity` Detemine which part of the image to cropped or to place the overlay. Accepted values: `auto`, `subject`, `face`, `sink`, `faceCenter`, `multipleFaces`, `multipleFacesCenter`, `north`, `northEast`, `northWest`, `west`, `southWest`, `south`, `southEast`, `east`, `center` ```vue ``` ### `effect` Apply a filter or an effect on the desired asset. See [Effects for images](https://cloudinary.com/documentation/image_transformation_reference#effect_parameter){rel=""nofollow""} for the full list of syntax and available effects. ```vue ``` ### `color` Color to use when text captions, shadow effect and colorize effect are in use. ```vue ``` ### `flags` One of more flags to alter the default transformation behavior. See [Flags for Images](https://cloudinary.com/documentation/image_transformation_reference#flags_parameter){rel=""nofollow""} for more information. ### `dpr` The target device pixel ratio for the asset. `auto` means automatically matching the DPR settings in user's device. ### `opacity` Adjust the opacity of the desired image. Scale: 0 to 100 (%). ```vue ``` ### `overlay` Create a layer **over** the base image. This can be use with `x`, `y`, `gravity` to customize the position of the overlay. ```vue [index.vue] ``` See [Overlay Documentation](https://cloudinary.com/documentation/image_transformation_reference#overlay_parameter){rel=""nofollow""} for more information. ### `underlay` Create a layer **below** a partial-transparent image. This can be use with `x`, `y`, `gravity` to customize the position of the overlay. ### `transformation` A pre-defined named transformation to apply to the asset. ### `zoom` Use together with `fit='crop'` or `fit='thumb'` to decide how much of original image/video surronding the face to keep using face detection. ```vue [index.vue] ``` ### `colorSpace` Color space to use for the delivery image URL. See [Color space Documentation](https://cloudinary.com/documentation/image_transformation_reference#color_space_parameter){rel=""nofollow""} for accepted values details. ```vue ``` ### `customFunc` Call a custom function on Cloudinary side. See [Custom Functions](https://cloudinary.com/documentation/custom_functions){rel=""nofollow""} for more details. ### `density` To define the density number when converting a vector file to image format. ### `aspectRatio` To crop or resize the asset to a new aspect ratio, for use with a crop/resize mode that determines how the asset is adjusted to the new dimensions. ::tip See [Cloudinary Image Transformation API](https://cloudinary.com/documentation/image_transformation_reference){rel=""nofollow""} for more details. :: # Contentful Integration between [Contentful](https://www.contentful.com){rel=""nofollow""} and the image module. To use this provider you just need to specify the base URL of your service in Contentful. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { contentful: {} } }) ``` # Directus Integration between [Directus](https://directus.io){rel=""nofollow""} and the image module. To use this provider you just need to specify the base URL of your project. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { directus: { // This URL needs to include the final `assets/` directory baseURL: 'http://localhost:8055/assets' } } }) ``` You can easily override default options: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { directus: { baseURL: 'http://mydirectus-domain.com/assets', modifiers: { withoutEnlargement: 'true', transforms: [['blur', 4], ['negate']] } } } }) ``` ## Modifiers All the default modifiers from [Directus documentation](https://docs.directus.io/reference/files.html#requesting-a-thumbnail){rel=""nofollow""} are available. ```vue ``` Since Directus exposes the full [sharp API](https://sharp.pixelplumbing.com/api-operation){rel=""nofollow""} through the `transforms` parameter, we can use it inside our `modifiers` prop: ```vue ``` ::note Note that the `transforms` parameter, as stated in the [Directus documentation](https://docs.directus.io/reference/files.html#advanced-transformations){rel=""nofollow""} , is basically a list of lists. This is to facilitate the use of those sharp functions, like [`normalise`](https://sharp.pixelplumbing.com/api-operation#normalise){rel=""nofollow""} , that would need multiple values in input: `transforms: [['normalise', 1, 99], ['blur', 4], ['negate']]` . :: # Fastly Integration between [Fastly](https://docs.fastly.com/en/guides/image-optimization-api){rel=""nofollow""} and the image module. To use this provider you just need to specify the base URL of your service in Fastly. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { fastly: { baseURL: 'https://www.fastly.io' } } }) ``` # Filerobot Integration between Scaleflex [Filerobot](https://www.scaleflex.com/digital-asset-management-filerobot){rel=""nofollow""} and the image module. To use this provider you just need to specify the base URL of your project. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { filerobot: { baseURL: 'https://.filerobot.com/', }, } }) ``` # Flyimg Integration between [Flyimg](https://flyimg.io){rel=""nofollow""} and the image module. [Flyimg](https://github.com/flyimg/flyimg){rel=""nofollow""} is a self-hosted, open-source image processing server built on ImageMagick. It accepts images from a source URL and applies transformations on the fly, caching results for subsequent requests. A managed SaaS version is also available at [flyimg.io](https://flyimg.io){rel=""nofollow""}. ## Setup ### Self‑hosted `baseURL` points to your **Flyimg server**. If you use relative image paths (e.g. ``), also set `sourceURL` to your **website's public URL** so that Flyimg can fetch the source image — it requires an absolute URL. Absolute `src` values (e.g. from a CDN) are passed through as-is and `sourceURL` is ignored for those. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { flyimg: { // URL of your Flyimg server baseURL: 'https://flyimg.example.com', // Public URL of your website — only needed for relative image paths sourceURL: 'https://www.example.com', } } }) ``` ::callout{type="warning"} **nginx users:** nginx's default `merge_slashes on` setting collapses consecutive slashes in URLs, which corrupts the embedded `https://` in Flyimg request paths (e.g. `https://flyimg.example.com/upload/-/https://www.example.com/photo.jpg` ). Add `merge_slashes off;` to the `server` block of your nginx config when reverse-proxying requests to Flyimg. :: ### Flyimg SaaS After [creating an instance](https://flyimg.io/documentation){rel=""nofollow""} you receive a unique subdomain (e.g. `img-abc123.flyimg.io`): ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { flyimg: { // Unique subdomain provided by Flyimg SaaS baseURL: 'https://img-abc123.flyimg.io', // Public URL of your website — only needed for relative image paths sourceURL: 'https://www.example.com', } } }) ``` ## Options | Option | Default | Description | | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `baseURL` | — | **Required.** URL of your Flyimg server or SaaS instance. | | `sourceURL` | — | Public base URL of your website. Only used for relative image paths — prefixed to make them absolute before passing to Flyimg. Absolute `src` values are unaffected. | | `processType` | `upload` | Flyimg process type: `upload` (serve the image) or `path` (return the path as text). | ## Modifiers In addition to the standard `width`, `height`, `quality`, `format`, and `fit` modifiers, the Flyimg provider exposes the full range of [Flyimg URL options](https://docs.flyimg.io/url-options/){rel=""nofollow""}. ### `fit` | Nuxt Image value | Flyimg behaviour | | -------------------- | --------------------------------------------------------------------------------- | | `contain` / `inside` | Scale to fit within the target rectangle preserving aspect ratio (Flyimg default) | | `cover` | Crop to fill the rectangle (`c_1`) | | `fill` | Stretch to fill without preserving aspect ratio (`par_0`) | | `outside` | ⚠️ Unsupported — ignored (dev-time warning emitted) | ### Additional Flyimg modifiers ```vue ``` Refer to the [Flyimg URL options documentation](https://docs.flyimg.io/url-options/){rel=""nofollow""} for the full list of supported parameters. # GitHub Easily use GitHub avatars in your Nuxt app. Just pass the username as the `src` prop and set the width or height. Since GitHub avatars must always be square, the largest dimension is used as the size. ```vue ``` ::note GitHub Avatars are returned with a minimum size of 1 and maximum size of 460 with a default size of 460. Values outside of the bounds will return the default. :: # Glide Integration between [Glide](https://glide.thephpleague.com){rel=""nofollow""} and the image module. To use this provider you just need to specify the base URL of your service in Glide. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { glide: { // baseURL of your Laravel application baseURL: 'https://glide.herokuapp.com/1.0' } } }) ``` # Gumlet Integration between [Gumlet](https://docs.gumlet.com){rel=""nofollow""} and the image module. To use this provider you just need to specify the base URL of your service in Gumlet. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { gumlet: { baseURL: 'https://demo.gumlet.io' } } }) ``` ## Gumlet `mode` Values Gumlet supports all the [standard values for `fit` property](https://image.nuxt.com/usage/nuxt-img#fit) of Nuxt image and Nuxt picture. ## Gumlet Modifiers Beside the [standard modifiers](https://image.nuxt.com/usage/nuxt-img#modifiers), you can also pass all gumlet-specific render API parameters to the `modifiers` prop. For a full list of these modifiers and their uses, check out [Gumlet's image transform API documentation](https://docs.gumlet.com/reference/image-transform-size#mode){rel=""nofollow""}. ## Gumlet Best Practices Some common best practices when using Gumlet, would be to include our `format=auto` parameter, which will automatically apply the best format for an image and compress the image as well. Combine this with some top of intelligent cropping and resizing and you will have a great image! ```vue ``` This will return a 300 x 500 image, which has been compressed, will display next-gen formats for a browser, and has been cropped intelligently to the face of the [woman in the hat](https://demo.gumlet.io/sea.jpeg?format=auto&w=300&h=500&compress=true){rel=""nofollow""}. # Hygraph Integration between [Hygraph](https://hygraph.com){rel=""nofollow""} and the image module. To use this provider you just need to specify the base URL of your project. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { hygraph: { baseURL: 'https://.graphassets.com/' } } }) ``` ## Modifiers All the default modifiers from [Hygraph's documentation](https://hygraph.com/docs/api-reference/content-api/assets){rel=""nofollow""} are available, plus additionally `auto_image` which lets Hygraph decide what image format is best for the user's browser and `quality` 0-100. ```vue ``` # ImageEngine Integration between [ImageEngine](https://imageengine.io){rel=""nofollow""} and the image module. At a minimum, you must configure the `imageengine` provider with the `baseURL` set to your ImageEngine Delivery Address: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { imageengine: { baseURL: 'https://xxxxx.imgeng.in' } } }) ``` ## ImageEngine `fit` Values The [standard values for `fit` property](https://image.nuxt.com/usage/nuxt-img#fit) map onto [ImageEngine Directives](https://imageengine.io/docs/directives){rel=""nofollow""} as follows: - `cover`: `m_cropbox` - `contain`: `m_letterbox` - `fill`: `m_stretch` - `inside`: `m_box`, this is the default fit method for the ImageEngine provider. - `outside`: This fit method is not supported and functions the same as `inside`. ## ImageEngine Modifiers In addition to the [standard modifiers](https://image.nuxt.com/usage/nuxt-img#modifiers), you can also use all [ImageEngine Directives](https://imageengine.io/docs/directives){rel=""nofollow""} by adding them to the `modifiers` property with the following attribute names: - `format`: `f` directive - `fit`: `m` directive - `passThrough`: `pass` directive - `sharpen`: `s` directive - `rotate`: `r` directive - `screenPercent`: `pc` directive - `crop`: `cr` directive - `inline`: `in` directive - `metadata`: `meta` directive > Note that the standard `quality` attribute is converted to the ImageEngine `cmpr` compression directive. `quality` is the opposite of compression, so 80% quality equals 20% compression. Since ImageEngine automatically adapts image quality the visitor's device, browser and network quality, it is recommended that you do not explicitly set the quality. If you want to completely disable all optimizations to an image, you should use `:modifiers="{ passThrough: 'true' }"`, which will serve the unaltered image. Example 1: Cropping an image to a width and height of 100x80, starting 10 pixels from the top and 20 pixels from the left: ```vue ``` Example 2: Instruct ImageEngine to keep the image's EXIF metadata (which is normally removed to reduce the image byte size): ```vue ``` ## ImageEngine Best Practices ### Automatic format and quality detection ImageEngine automatically detects the best format and quality for your image based on the characteristics of the specific device that requested it. This feature is very effective and it is not recommended that you disable it, but if you must, you can manually specify the format (ex: `format='webp'`) and quality (`quality='80'`). ### ImageEngine Settings ImageEngine allows you to set all of the modifiers/directives in the ImageEngine control panel under advanced settings. This is a good place to set default adjustments since you can modify them without having to make changes to your Nuxt codebase. If a directive is set in both Nuxt and the ImageEngine User-Adjustable Settings, the value in Nuxt takes priority. # ImageKit Integration between [ImageKit](https://docs.imagekit.io){rel=""nofollow""} and the image module. To use the ImageKit provider, you need to set your ImageKit account URL-endpoint as the base URL like below. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { imagekit: { baseURL: 'https://ik.imagekit.io/your_imagekit_id' } } }) ``` > You can get [URL-endpoint](https://docs.imagekit.io/integration/url-endpoints#default-url-endpoint){rel=""nofollow""} from your ImageKit dashboard - {rel=""nofollow""}. ## ImageKit `fit` Parameters In addition to the standard [`fit`](https://image.nuxt.com/usage/nuxt-img#fit) properties of Nuxt Image and Nuxt Picture, ImageKit offers more cropping and resizing options to the users: - `extract` - The output image has its height, width as requested, and the aspect ratio is preserved. Unlike the `cover` parameter, we extract out a region of the requested dimension from the original image. - `pad_extract` - This parameter is similar to `extract`. This comes in handy in scenarios where we want to extract an image of a larger dimension from a smaller image. So, the `pad_extract` mode adds solid colored padding around the image to match the exact size requested. Read ImageKit [crop and crop mode documentation](https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#crop-crop-modes-and-focus){rel=""nofollow""} for more details and examples of how it works. ## ImageKit Modifiers On top of the standard [Nuxt Image modifiers](https://image.nuxt.com/usage/nuxt-img#modifiers), a user can also leverage ImageKit-specific transformation parameters provided in the `modifier` prop. ### `focus` This parameter can be used along with resizing and cropping to focus on the desired part of the image. You can use focus parameter values like `left`, `right`, `top`, `bottom`, `center`, `top`, `left`, `bottom`, `right`, `top_left`, `top_right`, `bottom_left` and `bottom_right`. Custom coordinates can also be used to focus using parameter value `custom`. Learn more from [example](https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#example-focus-using-custom-coordinates){rel=""nofollow""}. Moreover, ImageKit also provides smart cropping that can automatically detect the most important part of the image using `auto`. And, `face` can be used to find a face (or multiple faces) in an image and focus on that. Check out ImageKit's documentation on [focus](https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations#focus-fo){rel=""nofollow""} to learn more. ### `blur` This can be used to blur an image. Use modifier `blur` to specify the Gaussian Blur radius that is to be applied to the image. Possible values include integers between `1` to `100`. ```vue ``` ### `effectGray` Turn your image to a grayscale version using the `effectGray` modifier. ```vue ``` ### `named` Use [named transformations](https://docs.imagekit.io/features/named-transformations){rel=""nofollow""} as an alias for an entire transformation string. For example, we can create a named transformation - `media_library_thumbnail` for a transformation string - `tr:w-100,h-100,c-at_max,fo-auto`. ### `border` Add a border to your images using the `border` modifier. You can also set its width and color. ```vue ``` ### `rotate` Use the `rotate` modifier to rotate your image. Possible values are - `0`, `90`, `180`, `270`, `360`, and `auto`. ```vue ``` ### `radius` Give rounded corners to your image using `radius`. Possible values are - positive integers and `max`. ```vue ``` ### `bg` Specify background color and its opacity for your image using the `bg` modifier. ```vue ``` > Read more about ImageKit crop, resize, and other common transformations [here](https://docs.imagekit.io/features/image-transformations/resize-crop-and-other-transformations){rel=""nofollow""}. ## Overlay Transformation Modifiers ImageKit's Nuxt Image integration enables you to apply overlays to [images](https://docs.imagekit.io/features/image-transformations/overlay-using-layers.md){rel=""nofollow""} using the `raw` parameter with the concept of [layers](https://docs.imagekit.io/features/image-transformations/overlay-using-layers.md#layers){rel=""nofollow""}. The `raw` parameter facilitates incorporating transformations directly in the URL. A layer is a special type of transformation that allows you to apply text and image overlay along with other transformation parameters. ### Overlay Image Overlay an image on top of another image (base image). You can use this to create dynamic banners, watermarking, etc. ```vue ``` ### Overlay Text You can overlay text on an image and apply various transformations to it as per your needs. ```vue ``` Read more about ImageKit's overlay using layers [here](https://docs.imagekit.io/features/image-transformations/overlay-using-layers){rel=""nofollow""}. ## Image Enhancement Modifiers ### `effectContrast` Enhance contrast of an image using the `effectContrast` modifier. ```vue ``` ### `effectSharpen` Sharpen the input image using the `effectSharpen` modifier. ```vue ``` ## List of supported transforms ImageKit's Nuxt Image integration provides an easy-to-remember name for each transformation parameter. It makes your code more readable. If you use a property that does not match any of the following supported options, it will be added in the URL as it is. | Supported Parameter Name | Translates to Parameter | | ------------------------ | ----------------------- | | bg | bg | | aspectRatio | ar | | x | x | | y | y | | xc | xc | | yc | yc | | oix | oix | | oiy | oiy | | oixc | oixc | | oiyc | oiyc | | crop | c | | cropMode | cm | | focus | fo | | radius | r | | border | b | | rotate | rt | | blur | bl | | named | n | | progressive | pr | | lossless | lo | | trim | t | | metadata | md | | colorProfile | cp | | defaultImage | di | | dpr | dpr | | effectSharpen | e-sharpen | | effectUSM | e-usm | | effectContrast | e-contrast | | effectGray | e-grayscale | | original | orig | > Learn more about [ImageKit's Image transformations](https://docs.imagekit.io/features/image-transformations){rel=""nofollow""} from the official documentation. # Imgix Integration between [Imgix](https://docs.imgix.com){rel=""nofollow""} and the image module. To use this provider you just need to specify the base URL of your service in Imgix. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { imgix: { baseURL: 'https://assets.imgix.net' } } }) ``` ## Imgix `fit` Values Beside the [standard values for `fit` property](https://image.nuxt.com/usage/nuxt-img#fit) of Nuxt image and Nuxt picture, Imgix offers the following for extra resizing experience: - `clamp` - Resizes the image to fit within the width and height dimensions without cropping or distorting the image, and the remaining space is filled with extended pixels from the edge of the image. The resulting image will match the constraining dimensions. The pixel extension is called an affine clamp, hence the value name, 'clamp'. - `clip` - The default fit setting for Imgix images. Resizes the image to fit within the width and height boundaries without cropping or distorting the image. The resulting image will match one of the constraining dimensions, while the other dimension is altered to maintain the same aspect ratio of the input image. - `facearea` - Finds the area containing all faces, or a specific face in an image, and scales it to specified width and height dimensions. Can be used in conjunction with [faceindex](https://docs.imgix.com/apis/rendering/face-detection/faceindex){rel=""nofollow""} to identify a specific face, as well as [facepad](https://docs.imgix.com/apis/rendering/face-detection/facepad){rel=""nofollow""} to include additional padded area around the face to zoom out from the immediate area around the faces. - `fillMax` - Resizes the image to fit within the requested width and height dimensions while preserving the original aspect ratio and without discarding any original image data. If the requested width or height exceeds that of the original, the original image remains the same size. The excess space is filled with a solid color or blurred version of the image. The resulting image exactly matches the requested dimensions. ## Imgix Modifiers Beside the [standard modifiers](https://image.nuxt.com/usage/nuxt-img#modifiers), you can also pass all Imgix-specific render API parameters to the `modifiers` prop. For a full list of these modifiers and their uses, check out [Imgix's image rendering API documentation](https://docs.imgix.com/apis/rendering){rel=""nofollow""}. ## Imgix Best Practices Some common best practices when using Imgix, would be to include our auto parameter, which will automatically apply the best format for an image and compress the image as well. Combine this with some top of intelligent cropping and resizing and you will have a great image! ```vue ``` This will return a 300 x 500 image, which has been compressed, will display next-gen formats for a browser, and has been cropped intelligently to the face of the [woman in the hat](https://assets.imgix.net/blog/woman-hat.jpg?w=300&h=500&fit=crop&crop=faces){rel=""nofollow""}. ## Additional Documentation You can find additional documentation and a step-by-step tutorial in an Imgix blog article titled [Using the New Nuxt Component with Imgix](https://blog.imgix.com/2021/09/14/nuxt-image-component){rel=""nofollow""}. # IPX Nuxt Image comes with a [preconfigured instance](https://image.nuxt.com/get-started/providers#default-provider) of [unjs/ipx](https://github.com/unjs/ipx){rel=""nofollow""} - an open source, self-hosted image optimizer based on [lovell/sharp](https://github.com/lovell/sharp){rel=""nofollow""}. ## Additional Modifiers You can use [additional modifiers](https://github.com/unjs/ipx/#modifiers){rel=""nofollow""} supported by IPX. **Example:** ```vue ``` ## Runtime Configuration You can update the options for `ipx` at runtime by passing the appropriate environment variable. For example: ```ts [nuxt.config.ts] export default defineNuxtConfig({ runtimeConfig: { ipx: { baseURL: process.env.NUXT_IPX_BASE_URL || '/_ipx', alias: { someAlias: process.env.NUXT_IPX_ALIAS_SOME_ALIAS || '' }, http: { domains: process.env.NUXT_IPX_HTTP_DOMAINS, }, }, }, }) ``` # Netlify When deploying your Nuxt applications to [Netlify's composable platform](https://docs.netlify.com/platform/overview){rel=""nofollow""}, the image module uses [Netlify Image CDN](https://docs.netlify.com/image-cdn/overview){rel=""nofollow""} to optimize and transform images on demand without impacting build times. Netlify Image CDN also handles content negotiation to use the most efficient image format for the requesting client. This provider is automatically enabled in Netlify deployments, and also when running locally using the [Netlify CLI](https://docs.netlify.com/cli/local-development){rel=""nofollow""}. You can also manually enable this provider. To do so, set the provider to `netlify` or add the following to your Nuxt configuration: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { provider: 'netlify' } }) ``` ## Local Development To test image transformations locally, use [Netlify Dev](https://docs.netlify.com/cli/local-development){rel=""nofollow""}. This feature of the Netlify CLI runs a local development server that mimics the Netlify production environment, including Netlify Image CDN. ## Remote Images To transform a source image hosted on another domain, you must first configure allowed domains: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { provider: 'netlify', domains: ['images.example.com'] } }) ``` ## Modifiers Beyond the [standard properties](https://image.nuxt.com/usage/nuxt-img){rel=""nofollow""}, you can use the [Netlify Image CDN `position` parameter](https://docs.netlify.com/image-cdn/overview/#position){rel=""nofollow""} as a modifier for Nuxt Image. ```vue ``` ## Deprecated Netlify Large Media option ::warning Netlify’s Large Media service is [deprecated](https://answers.netlify.com/t/large-media-feature-deprecated-but-not-removed/100804){rel=""nofollow""} . If this feature is already enabled for your site on Netlify and you have already set `provider: 'netlify'` in your Nuxt configuration, then this will be detected at build time and Large Media continues to work on your site as usual. You can also explicitly enable it by setting `provider: 'netlifyLargeMedia'` . However, new Large Media configuration is not recommended. :: ### Migrate to Netlify Image CDN To migrate from the deprecated Netlify Large Media option to the more robust Netlify Image CDN option, change `provider: 'netlify'` to `provider: 'netlifyImageCdn'`. This will enable the Netlify Image CDN service, even if large media is enabled on your site. ### Use deprecated Netlify Large Media option If you're not ready to migrate to the more robust Netlify Image CDN option, Netlify continues to support dynamic image transformation for all JPEG, PNG, and GIF files you have set to be tracked with [Netlify Large Media](https://docs.netlify.com/large-media/overview){rel=""nofollow""}. #### Large Media Modifiers In addition to `height` and `width`, the deprecated Netlify Large Media provider supports the following modifiers: ##### `fit` - **Default**: `contain` - **Valid options**: `contain` (equivalent to `nf_resize=fit`) and `fill` (equivalent to `nf_resize=smartcrop`) # None The `none` provider is a minimal pass-through provider that returns image URLs without applying any transformations or optimizations. This provider is useful when you want to use Nuxt Image components for consistent markup and loading behavior, but don't need actual image optimization. ## Usage ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { provider: 'none' } }) ``` ## Behavior When using the `none` provider: - No image transformations are applied (resizing, format conversion, etc.) - Modifiers are ignored - The original image URL is returned as-is - All Nuxt Image component features like lazy loading and placeholders still work This is particularly useful for development, testing, or when your images are already optimized and you just want the component interface. # Picsum Integration between [Lorem Picsum](https://picsum.photos/){rel=""nofollow""} and the image module. Lorem Picsum provides random placeholder images. It is useful during development or for demo purposes. To use this provider you just need to enable it in your Nuxt config: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { picsum: {} } }) ``` ## Usage ### Random image Get a random image with specific dimensions: ```vue ``` ### Specific image by ID Use `id/{id}` as the `src` to get a specific image: ```vue ``` ### Seeded random image Use `seed/{seed}` as the `src` to get a consistent random image based on a seed string: ```vue ``` ## Modifiers ### `grayscale` Return the image in grayscale. ```vue ``` ### `blur` Apply a blur effect to the image. Accepts values from 1 to 10. ```vue ``` ::note The `src` value must be either `id/{id}` for a specific image, `seed/{seed}` for a seeded random image, or `/` for a fully random image. Other `src` values are ignored and a random image will be returned. :: ::note Picsum does not support height-only resizing. When only `height` is provided without `width` , a square image of that dimension will be returned. :: # Prepr Integration between [Prepr](https://prepr.io){rel=""nofollow""} and Nuxt Image. To use this provider you just need to specify the `projectName` of your project in Prepr. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { prepr: { // E.g.: https://YourProjectName.prepr.io projectName: 'YourProjectName' } } }) ``` ## Modifiers The Prepr provider supports a number of additional modifiers. For a full list, check out the [Prepr documentation](https://docs.prepr.io/reference/rest/v1/assets-resizing){rel=""nofollow""}. All current transformations currently mentioned in Prepr docs are supported. For the time being you might find the following links useful: - [Assets Resizing via REST API](https://docs.prepr.io/reference/rest/v1/assets-resizing){rel=""nofollow""} - [Understanding your marketing and design team workflows](https://docs.prepr.io/managing-content/images){rel=""nofollow""} ::note prepr.io does not provide a way to restrict what domains can request assets to your project's CDN, nor limit the maximum size in `pixels` or `bytes` of images that are served from the CDN. :: ### Modifiers The following more readable modifiers are supported, in addition to Prepr's native modifiers: - `crop` is equivalent to `c` - `format` is equivalent to `format` - `height` is equivalent to `h` - `quality` is equivalent to `q` - `width` is equivalent to `w` ### `fit` In addition to the values specified in the Prepr docs, which are respected, the following options from the [default `fit` behavior](https://image.nuxt.com/usage/nuxt-img#fit) are supported: - `cover` - this will behave like the Prepr modifier `crop`, when passed without a value (defaults to `centre`) ::note For the time being, other `fit` options are not supported by this provider. :: # Prismic Integration between [Prismic](https://prismic.io/docs){rel=""nofollow""} and the image module. No specific configuration is required for Prismic support. You just need to specify `provider: 'prismic'` in your configuration to make it the default: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { prismic: {} } }) ``` You can also pass it directly to your component when you need it, for example: ```vue ``` ::note Prismic allows content writer to manipulate images through its UI (cropping, rezising, etc.). To preserve that behavior this provider does not strip query parameters coming from Prismic. Instead it only overrides them when needed, keeping developers in control. :: # Sanity Integration between [Sanity](https://www.sanity.io/docs/image-urls){rel=""nofollow""} and Nuxt Image. To use this provider you just need to specify the `projectId` of your project in Sanity. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { sanity: { projectId: 'yourprojectid', // Defaults to 'production' // dataset: 'development' } } }) ``` ## Modifiers The Sanity provider supports a number of additional modifiers. For a full list, check out the [Sanity documentation](https://www.sanity.io/docs/image-urls){rel=""nofollow""}. All of the modifiers mentioned in the Sanity docs are supported, with the following notes. ### Extra convenience modifiers The following more readable modifiers are also supported: - `background` - equivalent to `bg` - `download` - equivalent to `dl` - `sharpen` - equivalent to `sharp` - `orientation` - equivalent to `or` - `minHeight` or `min-height` - equivalent to `min-h` - `maxHeight` or `max-height` - equivalent to `max-h` - `minWidth` or `min-width` - equivalent to `min-w` - `maxWidth` or `max-width` - equivalent to `max-w` - `saturation` - equivalent to `sat` ### `fit` In addition to the values specified in the Sanity docs, which are respected, the following options from the [default fit behavior](https://image.nuxt.com/usage/nuxt-img#fit) are supported: - `cover` - this will behave like the Sanity modifier `crop` - `contain` - this will behave like the Sanity modifier `fill`, and defaults to filling with a white background. (You can specify your own background color with the `background` modifier.) - `inside` - this will behave like the Sanity modifier `min` - `outside` - this will behave like the Sanity modifier `max` - `fill` - this will behave like the Sanity modifier `scale` ::tip For compatibility with other providers, `fit: fill` is equivalent to the Sanity parameter `?fit=scale` . If you need the Sanity `?fit=fill` behavior, use `fit: contain` instead. :: ### `format` You can specify any of the formats suppored by Sanity. If this is omitted, the Sanity provider will default to `auto=format`. ### `crop` and `hotspot` You can pass your Sanity crop and hotspot image data as modifiers and Nuxt Image will correctly generate the `rect`, `fp-x`, and `fp-y` parameters for you. # Shopify Integration between [Shopify CDN](https://cdn.shopify.com/){rel=""nofollow""} and Nuxt Image. To use this provider, you just need to pass the image URL from the Storefront API response to the `src` prop. Configure the provider in your `nuxt.config.ts` (optional): ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { shopify: { baseURL: 'https://cdn.shopify.com/', } } }) ``` ## Modifiers The Shopify CDN provider supports the following default modifiers: - `width` - `height` - `format` - `quality` Additionally, the following modifiers are supported: - `padColor` - `crop` - `cropLeft` - `cropTop` - `cropWidth` - `cropHeight` ### Format The `format` modifier is supported. ```vue ``` ### Quality The `quality` modifier is supported. ```vue ``` ### Crop The `crop` modifier is supported with the following values: - `center` - `top` - `bottom` - `left` - `right` - `region` ```vue ``` #### Crop Region The `crop` modifier can also be used to crop an image to a specific region. ```vue ``` ### Pad color The `padColor` modifier can be used to pad an image with a background color. Must be a hex color value. ```vue ``` # Sirv Integration between [Sirv](https://sirv.com){rel=""nofollow""} and Nuxt image. To use Sirv provider, you need to set up your Sirv URL as the baseURL in the Nuxt Image module configuration, like this: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { sirv: { baseURL: 'https://youralias.sirv.com' } } }) ``` > Get your alias from your [Sirv account details page](https://my.sirv.com/#/account/settings){rel=""nofollow""} or set up a custom domain ([instructions](https://sirv.com/help/articles/multiple-domains){rel=""nofollow""}). ## Sirv `fit` parameters By default, Sirv will scale the image, preserving its aspect ratio, to fit within the smallest dimension. Here's the map of standard values for the [fit](https://image.nuxt.com/usage/nuxt-img#fit) property and how they're going to be interpreted by Sirv: - `fill`: `ignore` - `inside`: `fill` - `outside`: `fill` - `noUpscaling`: `noup`, this is the default option for Sirv image provider, so you don't need to specify it explicitly. ## `format` If no format is specified, Sirv will deliver your images in the [optimal](https://sirv.com/help/articles/dynamic-imaging/#optimal){rel=""nofollow""} format by default. Alternatively, you can specify a custom format for the image like this: ```vue ``` ## Sirv Modifiers To use Sirv-specific transformations, add them in the `modifier` prop. ### `profile` Use [Sirv profiles](https://sirv.com/help/profiles){rel=""nofollow""} to combine multiple transformation options into a single parameter. For example, you can combine `canvas`, `crop` and `watermark` parameters into a single profile and use it like this: ```vue ``` ### `canvas` Use the `canvas` modifier to add a canvas around your image. You can also set its width, height, color, and position. ### `sharpen` Sharpen the image using the `sharpen` modifier. ```vue ``` ### `frame` Add a frame/border to your images using the `frame` modifier. You can also set its width and color. ```vue ``` ### `rotate` Use the `rotate` modifier to rotate your image. You can specify the number of degrees to rotate the image by. ```vue ``` ### Color and light options Sirv has various [color manipulation options](https://sirv.com/help/articles/dynamic-imaging/color){rel=""nofollow""} like `grayscale`, `colorize`,`colortone`,`colorLevels`, as well as [light manipulation options](https://sirv.com/help/articles/dynamic-imaging/light){rel=""nofollow""} like `lightness`, `hue`, `saturation`, `highlights`, `shadows`, `brightness`, `exposure`, `contrast`. Here's how to convert an image to grayscale: ```vue ``` ### Watermarks and text overlays Using Sirv's Nuxt Image integration, you can overlay images or text over other images for watermarking or creating a dynamic banner using custom text! #### `watermark` Add an image overlay over your existing image using the `watermark` modifier. Used mostly for watermarking, but can be useful for creating banners, OG images, and personalization. Here's an example of a single watermark: ```vue ``` Find out more about Sirv watermarks [here](https://sirv.com/help/articles/dynamic-imaging/watermark){rel=""nofollow""}. #### Overlay Text You can add text overlays to your images and have full freedom over their positioning and looks. ```vue ``` More examples of text overlays can be found [here](https://sirv.com/help/articles/dynamic-imaging/text){rel=""nofollow""}. ## List of supported transformations Sirv's Nuxt Image integration uses intuitive names for each transformation. If you use a property that does not match any of the following supported options, it will be added in the URL as it is. | Supported Parameter Name | Translates to Parameter | Description | | ------------------------ | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | width | w | Width of image. | | height | h | Height of image. | | s | s | Resize the image by its biggest side | | quality | q | JPEG image quality (percentage). | | fit | scale.option | Image scaling options. | | profile | profile | Apply a Sirv [profile](https://sirv.com/help/articles/dynamic-imaging/profiles){rel=""nofollow""} | | format | format | Image format served (defaults to [optimal](https://sirv.com/help/articles/dynamic-imaging/#optimal){rel=""nofollow""}). | | webpFallback | webp-fallback | Image format for browsers without WebP support. | | subsampling | subsampling | Chroma subsampling to reduce JPEG file size. | | gifCompression | gif.lossy | Apply lossy compression, to reduce GIF file size. | | crop | crop.type | Automatically crop to edge of image contents; point of interest; or face. | | cropAr | crop.aspectratio | Aspect ratio of the crop | | cw | cw | Crop the image to a specific width. | | ch | ch | Crop the image to a specific height. | | cx | cx | Position to start image crop (from top). | | cy | cy | Position to start image crop (from left). | | cropPaddingX | crop.pad.x | Add padding to left/right of crop area | | cropPaddingY | crop.pad.y | Add padding to top/bottom of crop area. | | canvasHeight | canvas.height | Create a canvas around the image (height). | | canvasWidth | canvas.width | Create a canvas around the image (width). | | canvasAr | canvas.aspectratio | Aspect ratio of the canvas from 1-99 e.g. 16:9 | | canvasPosition | canvas.position | Position of the canvas behind the image. | | canvasBorderWidth | canvas.border.width | Adds additional width left and right of the canvas. | | canvasBorderHeight | canvas.border.height | Adds additional height above and below the canvas. | | canvasBorderColor | canvas.border.color | Color of the canvas border e.g. E0AA80 or red. | | canvasBorderOpacity | canvas.border.opacity | Opacity of the canvas border. | | watermark | watermark | Filepath of the image to be overlayed. | | watermarkPosition | watermark.position | Position of the watermark on the image. | | watermarkPositionGravity | watermark.position.gravity | sets the starting point for shifting the x & y values. | | watermarkPositionX | watermark.position.x | Position of the watermark (from left). | | watermarkPositionY | watermark.position.y | Position of the watermark (from top). | | watermarkWidth | watermark.scale.width | Width of watermark. | | watermarkHeight | watermark.scale.height | Height of watermark. | | text | text | Display text on your image. | | textBase64 | text.text64 | Alternative to text parameter, with Base64 encoding | | textSize | text.size | Width of text area in relation to image. | | textAlign | text.align | Align the multiline text. | | textPosition | text.position | Location of the text on the image. | | textPositionX | text.position.x | Location of the text (from left). | | textPositionY | text.position.y | Location of the text (from top). | | textPositionGravity | text.position.gravity | Master location of the text on the image. | | textFontSize | text.font.size | Fix the size of the text in px. | | textFontStyle | text.font.style | Style of the text. | | textFontFamily | text.font.family | Choose a font e.g. 'Open Sans'. | | textFontWeight | text.font.weight | Choose font weight (light, normal, semi-bold, bold, extra-bold). | | textColor | text.color | Text color e.g. E0AA80 or E0AA8020. | | textOpacity | text.opacity | Text opacity. | | textOutlineWidth | text.outline.width | Add an outline around the text. | | textoutlineColor | text.outline.color | Color of the text outline. | | textOutlineOpacity | text.outline.opacity | Opacity of the text outline. | | textOutlineBlur | text.outline.blur | Blur the edge of the text outline. | | textBackgroundColor | text.background.color | Background color e.g. E0AA80 or E0AA8020. | | textBackgroundOpacity | text.background.opacity | Background opacity. | | sharpen | sharpen | Sharpen the image. | | blur | blur | Blur the image. | | grayscale | grayscale | Make the image black & white. | | colorize | colorize | Overlay a color on the image. | | colorizeColor | colorize.color | The color of the colorize option. | | colorizeOpacity | colorize.opacity | Opacity of the color overlay. | | colortone | colortone | Change the color tone of the image. | | colortoneColor | colortone.color | Apply a color tone to an image. | | colortoneLevel | colortone.level | Set the level of blending with the original image. | | colortoneMode | colortone.mode | Apply the color tone to the entire image or shadows/highlights only. | | vignette | vigette.value | Adjust the depth of the vignette. | | vignetteColor | vigette.color | Add a vignette (dark edges) around the image. | | lightness | lightness | Change the lightness of the image. | | colorlevelBlack | colorlevel.black | Adjust black level of image. | | colorlevelWhite | colorlevel.white | Adjust white level of image. | | histogram | histogram | Display a histogram of RGB levels. | | hue | hue | Change the hue of the image. | | saturation | saturation | Change the saturation of the image. | | highlights | highlights | Change the highlights of the image. | | shadows | shadows | Change the shadows of the image. | | brightness | brightness | Change the brightness of the image. | | exposure | exposure | Change the exposure of the image. | | contrast | contrast | Change the contrast of the image. | | rotate | rotate | Number of degrees to rotate the image. | | flip | flip | Flip image vertically (mirror). | | flop | flop | Flip image horizontally (mirror). | | opacity | opacity | Opacity of PNG images. | | frameStyle | frame.style | Add a frame around the image. | | frameColor | frame.color | Frame color e.g. E0AA80 or E0AA8020. | | frameWidth | frame.width | Frame width. | | frameRimColor | frame.rim.color | Frame rim color e.g. E0AA80 or E0AA8020. | | frameRimWidth | frame.rim.width | Frame rim width. | | pdfPage | page | Page number of PDF when converted to image. | > Learn more about [Sirv's Image transformations](https://sirv.com/help/article/dynamic-imaging){rel=""nofollow""} from the official documentation. # Storyblok Integration between [Storyblok](https://www.storyblok.com/docs/api/image-service){rel=""nofollow""} and the image module. To use this provider you just need to specify the base URL of your service in Storyblok. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { storyblok: { baseURL: 'https://a.storyblok.com' } } }) ``` ## Storyblok Modifiers Check out available [Storyblok image service](https://www.storyblok.com/docs/api/image-service){rel=""nofollow""} modifiers. ### Resizing Check [Storyblok documentation](https://www.storyblok.com/docs/api/image-service/operations/resize){rel=""nofollow""} if you want to know more. the logic is: - If you do not define either width or height, the image will not be resized. - If you define only width or only height the image will be proportionately resized based on the one you defined. Example: ```vue ``` ### Fit in with background or not Check [Storyblok documentation](https://www.storyblok.com/docs/api/image-service/operations/fit-in){rel=""nofollow""} if you want to know more. If you want to use it just add a props `fit="in"`. Take care that Storyblok only support `fit-in`. You can also use the fill filters to fill your fit-in with a specific background. If you not defining value it will be transparent. Example: ```vue ``` ### Format Check [Storyblok documentation](https://www.storyblok.com/docs/api/image-service/operations/format){rel=""nofollow""} if you want to know more. You can modify your image format. Supported format are `webp`, `jpeg` and `png`. Example: ```vue ``` ### Quality Check [Storyblok documentation](https://www.storyblok.com/docs/api/image-service/operations/quality){rel=""nofollow""} if you want to know more. You can update your image quality by defining the quality filters. Example: ```vue ``` ### Facial detection Check [Storyblok documentation](https://www.storyblok.com/docs/api/image-service/operations/crop#smart-crop){rel=""nofollow""} if you want to know more. To have a smart crop just define a smart property inside modifier. Example: ```vue ``` ### Custom focal point Check [Storyblok documentation](https://www.storyblok.com/docs/api/image-service/operations/focal-point){rel=""nofollow""} if you want to know more. Storyblok allows you to focalize on a specific part of your image. Just use `focal` filters. Example: ```vue ``` # Strapi Integration between [Strapi](https://strapi.io){rel=""nofollow""} and the image module. No specific configuration is required. You just need to specify `strapi` in your configuration to make it the default: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { strapi: {} } }) ``` Override default options: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { strapi: { baseURL: 'http://localhost:1337/uploads' } } }) ``` ## Modifiers The `breakpoint` modifier is used to specify the size of the image. By default, when the image is uploaded and **Enable responsive friendly upload** Strapi setting is enabled in the settings panel the plugin will generate the following responsive image sizes: | Name | Largest Dimension | | -------- | ----------------- | | `small` | 500px | | `medium` | 750px | | `large` | 1000px | You can override the default breakpoints. See the [Upload configuration](https://docs.strapi.io/dev-docs/plugins/upload#configuration){rel=""nofollow""} in the Strapi documentation. If you don't set breakpoint modifier, the original image size will be used: ```vue ``` Define breakpoint modifier: ```vue ``` ::note Only one breakpoint can be modified per image. :: # Supabase Integration between [Supabase Storage](https://supabase.com/docs/guides/storage){rel=""nofollow""} and the image module. Supabase Storage provides image transformations powered by imgproxy. This provider enables optimization and resizing of images stored in your Supabase public buckets. ## Requirements - Supabase Pro tier or above (image transformations not available on free tier) - Public storage bucket (authenticated images not currently supported) ## Configuration To use this provider you need to specify the base URL pointing to your Supabase project's storage render endpoint. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { supabase: { baseURL: 'https://.supabase.co/storage/v1/render/image/public/' } } }) ``` ::note Replace `` with your Supabase project ID and `` with your public bucket name. :: ## Usage ```vue ``` ## Modifiers Supabase supports the following modifiers based on [Supabase's image transformation API](https://supabase.com/docs/guides/storage/serving/image-transformations){rel=""nofollow""}: ### `width` - **Type:** `Number` - **Range:** 1-2500 - **Description:** Target width in pixels ### `height` - **Type:** `Number` - **Range:** 1-2500 - **Description:** Target height in pixels ::note Supabase recommends specifying only `width` or `height` (not both) to maintain aspect ratio. When both are provided, the image will be resized and cropped according to the `resize` mode. :: ### `quality` - **Type:** `Number` - **Range:** 20-100 - **Default:** 80 - **Description:** Quality/compression level ### `resize` - **Type:** `String` - **Values:** `cover`, `contain`, `fill` - **Default:** `cover` - **Description:**Resize mode - `cover`: Fills specified dimensions while maintaining aspect ratio, crops excess - `contain`: Fits within dimensions while maintaining aspect ratio - `fill`: Resizes without aspect ratio preservation ### `format` - **Type:** `String` - **Values:** `origin` or specific format - **Description:** Output format. Use `origin` to keep the original format, otherwise images are automatically converted to WebP ## Example ```vue ``` ## Limitations - Only works with public buckets using `getPublicUrl()` - Authenticated images (signed URLs) are not currently supported - Maximum image size: 25MB - Maximum resolution: 50MP - Requires Supabase Pro tier or above ## Learn More - [Supabase Storage Image Transformations](https://supabase.com/docs/guides/storage/serving/image-transformations){rel=""nofollow""} - [Supabase Storage Documentation](https://supabase.com/docs/guides/storage){rel=""nofollow""} # Twicpics Integration between [Twicpics](https://www.twicpics.com/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider){rel=""nofollow""} and the image module. ## What is TwicPics? [Twicpics](https://www.twicpics.com/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider){rel=""nofollow""} is a Responsive Image Service Solution (SaaS) that enables on-demand responsive image generation. Using the TwicPics Provider you can, out of the box, benefit from at least: - performance of our network: global CDN, optimized protocols and competitive caching - ideal compression: modern technology and Next-Gen formats (TwicPics delivers [`WebP`](https://en.wikipedia.org/wiki/WebP){rel=""nofollow""} natively for accounting browsers and can also delivers [`avif`](https://en.wikipedia.org/wiki/AVIF){rel=""nofollow""}) And using the TwicPics API, you will be able to access all these features: [smart cropping with TwicPics focus auto](https://image.nuxt.com/#focus), [true color](https://image.nuxt.com/#truecolor), [flip](https://image.nuxt.com/#flip), [turn](https://image.nuxt.com/#turn), [crop](https://image.nuxt.com/#crop), [zoom](https://image.nuxt.com/#zoom). ## Requirement The only requirement is to have a TwicPics account. If you don't already have one, you can easily [create your own TwicPics account for free](https://account.twicpics.com/signup/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider){rel=""nofollow""}. ## Setup You just need to configure the `TwicPics` provider with the `baseURL` set to your TwicPics [Domain](https://www.twicpics.com/docs/getting-started/subdomain/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider){rel=""nofollow""}. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { twicpics: { baseURL: 'https://', // Feel free to use our demo domain to try the following examples. // baseUrl: 'https://demo.twic.pics' } } }) ``` ## Standard properties TwicPics Provider complies with the documentation of [nuxt-img](https://image.nuxt.com/usage/nuxt-img) and [nuxt-picture](https://image.nuxt.com/usage/nuxt-picture). ### fit `fit` determines how the image is resized in relation to the parameters `height` and `width`. TwicPics Provider supports all the the [standard values for `fit` property](https://image.nuxt.com/usage/nuxt-img#fit) of Nuxt image and Nuxt picture. Syntax: `fit='__cover__'` (default value) This will return a variant of your master image cropped to 300x300 while preserving aspect ratio. ```vue ``` This will return a variant of your master image resized to 300x300 with distortion. ```vue ``` This will bring your image back to a 300x600 area with respect to the ratio (1:1) using letterboxing. ```vue ``` The letterboxing strips are transparent areas. Feel free to select the color of your choice by using the [background](https://image.nuxt.com/#background) property. ```vue ``` ### format Specifies the output format. It can be an image format or a preview format. By default, [TwicPics](https://www.twicpics.com/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider){rel=""nofollow""} will 'guess' the best output format for the requesting browser, but you can use `format` to change this behavior. Syntax: `format='avif'|'heif'|'jpeg'|'png'|__'webp'__` [WebP](https://en.wikipedia.org/wiki/WebP){rel=""nofollow""} is the default format provided by [TwicPics](https://www.twicpics.com/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider){rel=""nofollow""} (if the browser supports it). Examples: This will return a variant of your image in `avif` format. ```vue ``` This will return a blurry preview of your image in `svg` format. ```vue ``` More informations [about format here](https://www.twicpics.com/docs/api/transformations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#output){rel=""nofollow""}. ### quality Specifies the output quality as a number between 1 (poor quality) and 100 (best quality). Syntax: `quality=`[`number`](https://www.twicpics.com/docs/api/manipulations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#number){rel=""nofollow""} [TwicPics](https://www.twicpics.com/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider){rel=""nofollow""} considers `quality`=70 as default value. **NB**: TwicPics automatically manages the returned quality according to the network performance for an optimized display speed even in difficult conditions. **NB** : when Data Saver is activated (android mobile only), default `quality`=10. Example: ```vue ``` More informations [about quality here](https://www.twicpics.com/docs/api/transformations/?utm_source=nuxt&utm_medium=organic&utm_campaign=quality#truecolor){rel=""nofollow""}. ### background `background` specifies a color that will show through transparent and translucent parts of the image. This will have no effect on images with no transparency nor translucency. Syntax: `background=`[`color`](https://www.twicpics.com/docs/api/manipulations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#color){rel=""nofollow""} Example: ```vue ``` ```vue ``` More informations [about background here](https://www.twicpics.com/docs/api/transformations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#background){rel=""nofollow""}. ## TwicPics modifiers In addition to the standard parameters, the specific features of the TwicPics API are accessible via the `modifiers` prop of `nuxt-img` or `nuxt-picture`. ```vue ``` [A complete list of these features and their uses is accessible here](https://www.twicpics.com/docs/api/transformations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider){rel=""nofollow""}. ### crop `crop` will extract a zone from the image which size is the given `crop` size. If no coordinates are given, the focus point will be used as a guide to determine where to start the extraction. If coordinates are given, they will be used to determine the top-left pixel from which to start the extraction and the focus point will be reset to the center of the resulting image. Syntax: `{ crop: `[`size`](https://www.twicpics.com/docs/api/manipulations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#crop-size){rel=""nofollow""}[`@coordinates`](https://www.twicpics.com/docs/api/manipulations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#coordinates){rel=""nofollow""}` }` ```vue ``` More informations [about `crop` here](https://www.twicpics.com/docs/api/transformations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#crop){rel=""nofollow""}. ### flip `flip` will invert the image horizontally, vertically or both depending on the expression provided. Syntax: `{ flip: 'both' | 'x' | 'y' }` ```vue ``` More informations [about `flip` here](https://www.twicpics.com/docs/api/transformations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#flip){rel=""nofollow""}. ### focus `focus` will set the focus point coordinates. It doesn't modify the output image in any way but will change the behavior of further transformations that take the focus point into account (namely cover, crop and resize). If `auto` is used in place of actual coordinates, the focus point will be chosen automagically for you! Syntax: `{ focus: `[`coordinates`](https://www.twicpics.com/docs/api/manipulations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#crop-coordinates){rel=""nofollow""}`|'auto' }` ```vue ``` *NB* : focus must be placed before the transformations modifying the output image (namely cover, crop and resize). More informations [about `focus` here](https://www.twicpics.com/docs/api/transformations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#focus){rel=""nofollow""}. ### truecolor `truecolor` can be used to prevent color quantization. If no boolean is provided, true is assumed. By default, quantization is allowed (truecolor=false). Quantization occurs whenever the output format is `png`. Use truecolor if you want to distribute substantially larger but more accurate images with translucency to users on browsers with no `WebP` support or when `png` is required as output format. ```vue ``` More informations [about `truecolor` here](https://www.twicpics.com/docs/api/transformations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#truecolor){rel=""nofollow""}. ### turn `turn` will change the orientation of the image. It accepts an angle in degrees or an expression. Angles will be rounded to the closest multiple of 90°. Syntax: `{ turn: `[`number`](https://www.twicpics.com/docs/api/manipulations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#number){rel=""nofollow""}` | 'flip' | 'left' | 'right' }` ```vue ``` More informations [about `turn` here](https://www.twicpics.com/docs/api/transformations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#turn){rel=""nofollow""}. ### zoom Zooms into the image by a factor equal or superior to 1 towards the focus point while preserving the image size. Syntax: `{ zoom: `[`number`](https://www.twicpics.com/docs/api/manipulations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#number){rel=""nofollow""}` }` ```vue ``` More informations [about `zoom` here](https://www.twicpics.com/docs/api/transformations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider#zoom){rel=""nofollow""}. ## Combination of parameters You can combine several transformations of the [TwicPics API](https://www.twicpics.com/docs/api/transformations/?utm_source=nuxt&utm_medium=organic&utm_campaign=provider){rel=""nofollow""}. Be aware that the order of the parameters can be significant. Example: This will return a variant of image for which we have, in order: 1. cropped the image from the center to 16:9 aspect ratio 2. then placed the focus on the center of interest of the cropped image 3. then rotate the image 90° to the left The result is a 9:16 (not 16:9) image with a possibly false area of interest. ```vue ``` This will return a variant of your image for which we have, in order: 1. placed the focus on the center of interest of the original image 2. then cropped the image to 16:9 from the center of interest 3. then rotated the image 90° to the left The result is a cropped image with the area of interest retained and displayed in 16:9 format. ```vue ``` ## Dealing with image ratio Let's say you want to display an image in 4:3 aspect ratio with a width of 300px. ```vue ``` Or, with `focus`='auto' ```vue ``` ## Go further with TwicPics TwicPics offers a [collection of web components](https://www.npmjs.com/package/@twicpics/components){rel=""nofollow""} that will allow you to exploit all its power : - Pixel Perfect - Layout Driven - Ideal Compression - Lazy Loading - LQIP - CLS Optimization A specific integration to Nuxt is available [here](https://github.com/TwicPics/components/blob/main/documentation/nuxt2.md){rel=""nofollow""}. # Umbraco Integration between [Umbraco](https://umbraco.com){rel=""nofollow""} and the image module. This provider is designed for images served through Umbraco's built-in ImageSharp-based image processing pipeline. To use this provider, configure the base URL of your Umbraco site: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { umbraco: { baseURL: 'https://your-umbraco-site.com' } } }) ``` You can then use the provider with `NuxtImg` or `NuxtPicture`: ```vue ``` ## Options ### `baseURL` - Type: **String** - Default: `''` Base URL for your Umbraco site. This is prepended to relative image paths such as `/media/...`. If you already pass absolute Umbraco media URLs as `src`, `baseURL` can be omitted: ```vue ``` ## Modifiers The Umbraco provider maps Nuxt Image modifiers to Umbraco/ImageSharp query parameters: | Nuxt modifier | Query parameter | Description | | ---------------- | --------------- | ----------------------------------------------------- | | `width` | `width` | Output width in pixels | | `height` | `height` | Output height in pixels | | `format` | `format` | Output format, for example `webp`, `jpg`, `png` | | `quality` | `quality` | Encoder quality | | `fit` | `rmode` | Resize mode | | `sampler` | `rsampler` | Resampling algorithm | | `anchorPosition` | `ranchor` | Anchor position for crop/pad operations | | `focalPointXY` | `rxy` | Exact focal point as `x,y` values between `0` and `1` | If only one of `width` or `height` is provided, the original aspect ratio is preserved. ### `fit` Supported values: - `boxpad` - `crop` - `manual` - `max` - `min` - `pad` - `stretch` - `contain` - `cover` The standard Nuxt Image values `contain` and `cover` are mapped to their ImageSharp equivalents: `contain` becomes `rmode=max` and `cover` becomes `rmode=crop`. ```vue ``` ### `focalPointXY` Use `focalPointXY` when you want to crop around an exact focal point. The value must be a comma-separated `x,y` pair between `0` and `1`. ```vue ``` ### `anchorPosition` Use `anchorPosition` to control how the image is anchored when using resize modes such as `crop` or `pad`. Supported values: - `top` - `topleft` - `topright` - `left` - `center` - `right` - `bottom` - `bottomleft` - `bottomright` ```vue ``` ### `sampler` Use `sampler` to control the resampling algorithm used during resize operations. Supported values: - `bicubic` - `nearest` - `box` - `mitchell` - `catmull` - `lanczos2` - `lanczos3` - `lanczos5` - `lanczos8` - `welch` - `robidoux` - `robidouxsharp` - `spline` - `triangle` - `hermite` ```vue ``` ## Notes ### ImageSharp and Umbraco processing Umbraco uses ImageSharp.Web for image processing, so this provider works by generating the same query parameters Umbraco already understands for resize, format, quality, focal point and related operations. ### Set crops Umbraco supports using set crops for images. These however, aren't currently supported. ### HMAC protected image URLs If your Umbraco setup has `Umbraco:CMS:Imaging:HMACSecretKey` enabled, image requests can require an HMAC signature. This provider does not currently generate that signature, so transformed URLs may be rejected unless signing is handled elsewhere. ### Resize limits Umbraco can enforce maximum resize dimensions through its imaging settings. If the requested dimensions exceed your configured limits, resizing may not be applied. ## Example ```vue ``` ## More information For the underlying processing behavior and available resize semantics, see the [Umbraco Image Cropper docs](https://docs.umbraco.com/umbraco-cms/fundamentals/backoffice/property-editors/built-in-umbraco-property-editors/image-cropper){rel=""nofollow""} and the [ImageSharp processing commands docs](https://docs.sixlabors.com/articles/imagesharp.web/processingcommands.html){rel=""nofollow""}. # Unsplash Integration between [Unsplash](https://unsplash.com/documentation#dynamically-resizable-images){rel=""nofollow""} and the image module. See [Unsplash License](https://unsplash.com/license){rel=""nofollow""} for what usage is permitted. ## Dynamically resizable images Every image returned by the Unsplash API is a dynamic image URL, which means that it can be manipulated to create new transformations of the image by simply adjusting the query parameters of the image URL. This enables resizing, cropping, compression, and changing the format of the image in realtime client-side, without any API calls. Under the hood, Unsplash uses [Imgix](https://image.nuxt.com/providers/imgix), a powerful image manipulation service to provide dynamic image URLs. ## Supported parameters Unsplash officially support the parameters: - `w, h`: for adjusting the width and height of a photo - `crop`: for applying cropping to the photo - `fm`: for converting image format - `auto=format`: for automatically choosing the optimal image format depending on user browser - `q`: for changing the compression quality when using lossy file formats - `fit`: for changing the fit of the image within the specified dimensions - `dpr`: for adjusting the device pixel ratio of the image The other parameters offered by Imgix can be used, but we don’t officially support them and may remove support for them at any time in the future. > 💫 Tip > The API returns image URLs containing an ixid parameter. All resizing and manipulations of image URLs must keep this parameter as it allows for your application to report photo views and be compliant with the API Guidelines. # Uploadcare Integration between [Uploadcare](https://uploadcare.com){rel=""nofollow""} and the Nuxt Image module. ## Usage To use images from uploadcare, specify the provider as `uploadcare` and set the image src to the UUID provided on the dashboard. ```vue [page.vue] ``` ## Modifiers To see all possible modifiers and their options, check out the [image transformations documentation](https://uploadcare.com/docs/transformations/image){rel=""nofollow""} or the [URL API Reference](https://uploadcare.com/api-refs/url-api){rel=""nofollow""}. Types are provided for the following modifiers: ```ts [src/types/module.ts] // Image Compression format: 'jpeg' | 'png' | 'webp' | 'auto' quality: 'smart' | 'smart_retina' | 'normal' | 'better' | 'best' | 'lighter' | 'lightest' progressive: 'yes' | 'no' strip_meta: 'all' | 'none' | 'sensitive' // Image Geometry preview: `${number}x${number}` // Height x Width resize: `${number}x${number}` | `${number}x`| `x${number}` smart_resize: `${number}x${number}` crop: string | string[] scale_crop: string | string[] border_radius: string | string[] setfill: string // 3, 6 or 8 digit hex color zoom_objects: string // 1 to 100 ``` Please feel free to open a PR to improve support for additional operations. ## Configuration > By default, all file URLs use the `ucarecdn.com` domain. By setting a custom CDN CNAME, file URLs can use `cdn.mycompany.com` instead. See the [Uploadcare documentation](https://uploadcare.com/docs/delivery/cdn/#custom-cdn-cname){rel=""nofollow""} for how to enable a custom domain in your project. To tell Nuxt Image about the custom CDN name, use the following configuration: ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { uploadcare: { cdnURL: 'cdn.mycompany.com' } } }) ``` # Vercel When deploying your Nuxt applications to [Vercel](https://vercel.com){rel=""nofollow""} platform, image module can use [Vercel's CDN](https://vercel.com/docs/cdn){rel=""nofollow""} to optimize images on demand. This provider will be enabled by default in Vercel deployments. ::warning Vercel requires you to explicitly list all the widths used in your app. [See example below.](https://image.nuxt.com/#sizes) :: ## Domains To use external URLs (images not in `public/` directory), hostnames should be whitelisted. **Example:** ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { domains: ['avatars0.githubusercontent.com'] } }) ``` ## Sizes You need to specify **every custom width** used in ``, `` or `$img` for Vercel to resize them properly ([source](https://vercel.com/docs/build-output-api/v3/configuration#api){rel=""nofollow""}). If a width is not defined, image will fallback to the next bigger width. ::tip Don't forget to also take into account [`densities`](https://image.nuxt.com/get-started/configuration#densities) . :: **Example:** ::code-group ```vue [index.vue] ``` ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { screens: { icon: 40, icon2x: 80 } // will be converted to sizes: [40, 80] for Vercel output API } }) ``` :: ## Options ### `formats` - Type: **String []** (optional) Specify the image format allow list for optimization. By default, the provider set the following formats: `['image/webp', 'image/avif']`. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { vercel: { formats: ['image/webp'] } } }) ``` # Weserv Weserv offers a wide range of image transformation for all JPEG, PNG, and GIF files. ## Modifiers In addition to `height` and `width`, the Weserv provider supports numerous modifiers documented [here](https://images.weserv.nl/docs/quick-reference.html){rel=""nofollow""}. # Custom Provider ## Provider Entry The runtime will receive a source, image modifiers and its provider options. It is responsible for generating a URL for optimized images, and needs to be isomorphic because it may be called on either server or client. ```ts [providers/my-provider.ts] import { joinURL } from 'ufo' import { createOperationsGenerator, defineProvider } from '@nuxt/image/runtime' const operationsGenerator = createOperationsGenerator() export default defineProvider<{ baseURL?: string }>({ getImage (src, { modifiers, baseURL }) { if (!baseURL) { // also support runtime config baseURL = useRuntimeConfig().public.siteUrl } const operations = operationsGenerator(modifiers) return { url: joinURL(baseURL, src + (operations ? '?' + operations : '')) } } }) ``` ### Parameters - `src`: Source path of the image. - `modifiers`: List of image modifiers that are defined in the image component or as a preset. - `ctx`: (`ImageCTX`) Image module runtime context - `options`: (`CreateImageOptions`) Image module global runtime options - `$img`: The [$img helper](https://image.nuxt.com/usage/use-image) **Note:** Values in `ctx` might change. Use it with caution. ### Return - `url`: Absolute or relative URL of optimized image. ## Use Your Provider ### Register provider After you create your own provider, you should register it in the `nuxt.config`. In order to do that create a property inside `image.provider`. ```ts [nuxt.config.ts] export default defineNuxtConfig({ image: { providers: { myProvider: { name: 'myProvider', // optional value to overrider provider name provider: '~/providers/my-provider.ts', // Path to custom provider options: { // ... provider options baseURL: 'https://site.com' } } } } }) ``` There are plenty of useful utilities that can be used to write providers by importing from `@nuxt/image/runtime`. See [src/runtime/providers](https://github.com/nuxt/image/tree/main/src/runtime/providers){rel=""nofollow""} for more info. ### Usage Set attribute `provider` as your custom provider name. ```vue [pages/index.vue] ``` # Static Images If you are building a static site using `nuxt generate`, Nuxt Image will optimize and save your images locally when your site is generated - and deploy them alongside your generated pages. If you disabled server-side rendering (`ssr: false` in the `nuxt.config`), Nuxt Image won't be able to optimize your images during the static generation process. In that case, you can tell Nuxt to pre-render images by using the `nitro.prerender.routes` option: ```ts [nuxt.config.ts] export default defineNuxtConfig({ ssr: false, nitro: { prerender: { routes: [ '/_ipx/w_120/market.jpg', '/_ipx/w_140/market.jpg', // etc. ] } } }) ``` # Optimized Images for your Nuxt Apps :the-gradient ::u-page-hero --- orientation: horizontal --- :the-illustration{.hidden.lg:flex} #title Optimized Images for your [Nuxt Apps]{.text-primary} #description Plug-and-play image optimization for Nuxt apps. Resize and transform your images using built-in optimizer or your favorite images CDN. #links :::u-button --- icon: i-ph-rocket-launch-duotone size: xl to: https://image.nuxt.com/get-started/installation --- Get started ::: :copy-code-input{source="npx nuxt module add image"} :: ::u-container :::u-page-logos --- title: Trusted by the best frontend teams --- #default{unwrap="p"} ![OpenAI](https://image.nuxt.com/brands/openai.svg){height="28" preload="" width="104"}![Sephora](https://image.nuxt.com/brands/sephora.svg){height="28" preload="" width="217"}![Hyundai](https://image.nuxt.com/brands/hyundai.svg){height="28" preload="" width="205"}![Gitlab](https://image.nuxt.com/brands/gitlab.svg){height="28" preload="" width="129"}![Emma](https://image.nuxt.com/brands/emma.svg){heiht="28" preload="" width="115"} ::: :: ::u-page-section #title Get the most of your images with :br [dynamic features]{.text-primary} #features :::u-page-card --- spotlight: true icon: i-ph-image-duotone to: https://image.nuxt.com/usage/nuxt-img --- #title Drop-in Replacement #description Leverage `nuxt-img` and `nuxt-picture` drop-in replacement for the native `img` and `picture` elements. ::: :::u-page-card --- spotlight: true icon: i-ph-crop to: https://image.nuxt.com/providers/ipx --- #title Built-in Resizer #description Unlock the power of our built-in image resizer and transformer with IPX. ::: :::u-page-card --- spotlight: true icon: i-ph-plug-duotone to: https://image.nuxt.com/get-started/providers --- #title 20+ Providers Supported #description Choose over 20 image providers to optimize your images, no vendor lock-in. ::: :::u-page-card --- spotlight: true icon: i-ph-frame-corners to: https://image.nuxt.com/usage/nuxt-img#sizes --- #title Responsive Ready #description Nuxt Image dynamically generates responsive sizes. Your visuals adapt effortlessly to every screen size, offering a seamless user experience. ::: :::u-page-card --- spotlight: true icon: i-ph-magic-wand-duotone to: https://image.nuxt.com/usage/nuxt-img#format --- #title Future-Proof Formats #description Embrace the future of visual optimization with support for modern formats like webp and avif. ::: :::u-page-card --- spotlight: true icon: i-ph-rocket-launch-duotone to: https://image.nuxt.com/get-started/installation --- #title Streamlined Performance #description Deliver visually stunning content with lightning-fast load times, keeping your audience engaged and delighted. ::: :: ::u-page-section --- orientation: horizontal --- :::provider-list --- providers: - caisy - bunny - builderio - cloudflare - cloudimage - cloudinary - directus - fastly - filerobot - glide - gumlet - hygraph - imageengine - imagekit - imgix - ipx - netlify - prepr - prismic - sanity - shopify - storyblok - strapi - twicpics - unsplash - uploadcare - vercel - weserv --- ::: #title Choose your :br [favorite provider]{.text-primary} #description Nuxt Image supports multiple providers for high performance. Providers are integrations between Nuxt Image and third-party image transformation services. Each provider is responsible for generating correct URLs for that image transformation service. Nuxt Image can also be configured to work with any external image transformation service. #links :::u-button --- icon: i-ph-rocket-launch-duotone size: xl to: https://image.nuxt.com/get-started/providers --- Get started ::: ::