Unverified Commit 749c8e72 authored by Jiwon Choi's avatar Jiwon Choi Committed by GitHub

docs: add details about `images` options at `next.config.js` options (#63712)

Since the [image configuration
options](https://nextjs.org/docs/app/api-reference/components/image#configuration-options)
have all the necessary options for `images` that need to be addressed in
the [next.config.js
options](https://nextjs.org/docs/app/api-reference/next-config-js/images),
we refer to them without making significant changes.

Also, `use client` is required to use the `loader` option in the App
Router but not Pages.

Closes #62793

---------
Co-authored-by: 's avatarSteven <steven@ceriously.com>
parent b90dcdd0
......@@ -128,6 +128,8 @@ A `loader` is a function returning a URL string for the image, given the followi
Here is an example of using a custom loader:
<AppOnly>
```js
'use client'
......@@ -150,12 +152,34 @@ export default function Page() {
}
```
<AppOnly>
> **Good to know**: Using props like `loader`, which accept a function, requires using [Client Components](/docs/app/building-your-application/rendering/client-components) to serialize the provided function.
</AppOnly>
<PagesOnly>
```js
import Image from 'next/image'
const imageLoader = ({ src, width, quality }) => {
return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}
export default function Page() {
return (
<Image
loader={imageLoader}
src="me.png"
alt="Picture of the author"
width={500}
height={500}
/>
)
}
```
</PagesOnly>
Alternatively, you can use the [loaderFile](#loaderfile) configuration in `next.config.js` to configure every instance of `next/image` in your application, without passing a prop.
### `fill`
......@@ -280,12 +304,24 @@ Remember that the required width and height props can interact with your styling
### `onLoadingComplete`
<AppOnly>
```jsx
'use client'
<Image onLoadingComplete={(img) => console.log(img.naturalWidth)} />
```
</AppOnly>
<PagesOnly>
```jsx
<Image onLoadingComplete={(img) => console.log(img.naturalWidth)} />
```
</PagesOnly>
> **Warning**: Deprecated since Next.js 14 in favor of [`onLoad`](#onload).
A callback function that is invoked once the image is completely loaded and the [placeholder](#placeholder) has been removed.
......@@ -481,7 +517,9 @@ module.exports = {
This must point to a file relative to the root of your Next.js application. The file must export a default function that returns a string, for example:
```js
<AppOnly>
```js filename="my/image/loader.js"
'use client'
export default function myImageLoader({ src, width, quality }) {
......@@ -489,6 +527,18 @@ export default function myImageLoader({ src, width, quality }) {
}
```
</AppOnly>
<PagesOnly>
```js filename="my/image/loader.js"
export default function myImageLoader({ src, width, quality }) {
return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}
```
</PagesOnly>
Alternatively, you can use the [`loader` prop](#loader) to configure each instance of `next/image`.
Examples:
......
......@@ -18,22 +18,36 @@ module.exports = {
This `loaderFile` must point to a file relative to the root of your Next.js application. The file must export a default function that returns a string, for example:
```js
<AppOnly>
```js filename="my/image/loader.js"
'use client'
export default function myImageLoader({ src, width, quality }) {
return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}
```
<AppOnly>
Alternatively, you can use the [`loader` prop](/docs/app/api-reference/components/image#loader) to pass the function to each instance of `next/image`.
> **Good to know**: Customizing the image loader file, which accepts a function, requires using [Client Components](/docs/app/building-your-application/rendering/client-components) to serialize the provided function.
To learn more about configuring the behavior of the built-in [Image Optimization API](/docs/app/building-your-application/optimizing/images) and the [Image Component](/docs/app/api-reference/components/image), see [Image Configuration Options](/docs/app/api-reference/components/image#configuration-options) for available options.
</AppOnly>
<PagesOnly>
```js filename="my/image/loader.js"
export default function myImageLoader({ src, width, quality }) {
return `https://example.com/${src}?w=${width}&q=${quality || 75}`
}
```
Alternatively, you can use the [`loader` prop](/docs/pages/api-reference/components/image#loader) to pass the function to each instance of `next/image`.
To learn more about configuring the behavior of the built-in [Image Optimization API](/docs/pages/building-your-application/optimizing/images) and the [Image Component](/docs/pages/api-reference/components/image), see [Image Configuration Options](/docs/pages/api-reference/components/image#configuration-options) for available options.
</PagesOnly>
## Example Loader Configuration
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment