[docs] Add <Link> and <Image> docs and examples on Next.js integration page

[Demianeen]

Related page

https://mui.com/material-ui/integrations/nextjs/

Kind of issue

Missing information

Issue description

Next.js has its own routing and image optimization mechanisms, but I don't see docs mentioning it. Should we add it?

Context

Building Next.js app with MUI

Search keywords: NextLink NextImage Next Link Next Image

[Demianeen]

For Next.js Link I currently have integration like this:

import NextLink from 'next/link'

const LinkBehaviour = forwardRef<
  HTMLAnchorElement,
  ComponentProps<typeof NextLink>
  >(function LinkBehaviour(props, ref) {
  return <NextLink ref={ref} {...props} />
})

export const theme = createTheme({
  components: {
    MuiLink: {
      defaultProps: {
      	component: LinkBehaviour,
      },
    },
})

I am not sure it will work with Button's href prop though. I also am not sure how to integrate Image properly myself. I can pass Image inside an avatar to display it but I am not sure this can be called "integration":

<Avatar>
  <Image src="/profile.jpg" alt="Profile" width={40} height={40} />
</Avatar>

[mj12albert]

We have example repos for Next.js integration, e.g. https://github.com/mui/material-ui/tree/master/examples/material-ui-nextjs-ts

Example usage of Link/NextLink is here: https://github.com/mui/material-ui/blob/master/examples/material-ui-nextjs-ts/src/app/page.tsx#L25-L27

I also am not sure how to integrate Image properly myself

AFAIK Next.js Image is just a component, Material UI doesn't have one, so there isn't anything to "integrate" like Link/NextLink

[Demianeen]

We have example repos for Next.js integration, e.g. https://github.com/mui/material-ui/tree/master/examples/material-ui-nextjs-ts

It passes it as component in one place, which mean there is huge chance that somebody will forget to change Link or Button with href to it. The issue with Link can be solved with theme. But I wonder if Button with href would render MUI Link despite Next.js defined one in theme or would it render Next.js Link. It can be beneficial to cover this in docs for example as a lot of people would just use Next.js integration guide. I personally didn't even know the example repo existed

AFAIK Next.js Image is just a component, Material UI doesn't have one, so there isn't anything to "integrate" like Link/NextLink

I mean to have the mui components use Image from next.js instead of normal img component. So, for example:

<Avatar alt="Remy Sharp" src="/static/images/avatar/1.jpg" />

Would actually render Next Image instead of default img element. Is this possible with Mui?

[mj12albert]

For Avatar, the image can be replaced with NextImage with the slots prop:

import Image from 'next/image'

<Avatar slots={{
  img: Image
}} />

We're still standardizing slots for the whole library so it's not super well documented yet (also see https://mui.com/material-ui/migration/migrating-from-deprecated-apis/#inner-element-overrides)

For Link, it's kind of documented all over the place:

• https://mui.com/material-ui/react-link/#third-party-routing-library
• https://mui.com/material-ui/integrations/routing/#next-js-pages-router

I agree that it's probably better to centralize all the Next.js/Link related info on the dedicated Next.js integration page

[Demianeen]

@mj12albert, indeed it works. Though, it is a bit more tricky. Next Image is not drop-in replacement for img. It has extra (and slightly different) required props (e.g., src can be a string | StaticImport, it has a mandatory alt, width, height etc.). So you get a type mismatch because the Next <Image> type does not line up with the HTML <img> type MUI wants.

So, for example, this code works but throws ts error that img and Image types not match:

<Avatar
	src={company.logoUrl ? company.logoUrl : undefined}
	slots={{
		img: Image,
	}}
	slotProps={{
		img: {
			width: 164,
			height: 164,
		},
	}}
	sx={{ width: 164, height: 164 }}
/>

I assume there we can do the type augmentation, but I then I get an typescript error that Subsequent property declarations must have the same type. Would it be possible to overwrite the types?

As a temporary workaround I created AppAvatar that handles the mui Avatar and Next Image integration and added mui Avatar to restricted-imports:

// AppAvatar.tsx
import type { AvatarProps } from '@mui/material'
// eslint-disable-next-line no-restricted-imports
import { Avatar } from '@mui/material'
import Image from 'next/image'

export interface AppAvatarProps {
	src?: string
	alt: string
	width?: number
	height?: number
}

export function AppAvatar<
	RootComponent extends React.ElementType = 'div',
	AdditionalProps = object,
>({
	src,
	alt,
	width = 40,
	height = 40,
	sx,
	...props
}: AppAvatarProps & AvatarProps<RootComponent, AdditionalProps>) {
	return (
		<Avatar
			sx={{
				width: width,
				height: height,
				...sx,
			}}
			{...props}
		>
			{src && <Image src={src} width={width} height={height} alt={alt} />}
		</Avatar>
	)
}

// eslint.config.mjs
'no-restricted-imports': [
	2,
	...
	{
		name: '@mui/material',
		importNames: ['Avatar'],
		message: 'Please use `@/shared/ui/AppAvatar` instead.',
	},
	{
		name: '@mui/material/Avatar',
		message: 'Please use `@/shared/ui/AppAvatar` instead.',
	},
]

[mj12albert]

Next Image is not drop-in replacement for img. It has extra (and slightly different) required props (e.g., src can be a string | StaticImport, it has a mandatory alt, width, height etc.). So you get a type mismatch because the Next <Image> type does not line up with the HTML <img> type MUI wants.

I see ~ in that case I would suggest opening a separate issue for better integrating Avatar with Next.js Image using the slots API 😄