[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