[material-ui-nextjs] Add Link integration component

babel.config.js

@@ -31,6 +31,7 @@ module.exports = function getBabelConfig(api) {
     '@mui/base': resolveAliasPath('./packages/mui-base/src'),
     '@mui/utils': resolveAliasPath('./packages/mui-utils/src'),
     '@mui/material-next': resolveAliasPath('./packages/mui-material-next/src'),
+    '@mui/material-nextjs': resolveAliasPath('./packages/mui-material-nextjs/src'),
     '@mui/joy': resolveAliasPath('./packages/mui-joy/src'),
     '@mui/zero-runtime': resolveAliasPath('./packages/zero-runtime/src'),
     docs: resolveAliasPath('./docs'),

docs/data/material/guides/nextjs/nextjs.md

@@ -59,6 +59,35 @@ This option ensures that the styles generated by Material UI will be wrapped in
 
 To learn more about it, see [the MDN CSS layer documentation](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer).
 
+### Link
+
+The package provides a thin wrapper Link component that combines the functionality of the Next.js [Link](https://nextjs.org/docs/api-reference/next/link) and the styles of Material UI [Link](https://mui.com/components/links/).
+
+You can pass any props supported by both components to the Link.
+
+```js
+import { Link } from '@mui/material-nextjs/v13-appRouter'; // or `v14-appRouter` if you are using Next.js v14
+
+function Nav() {
+  return (
+    <div>
+      <Link href="/dashboard" variant="caption" sx={{ bgcolor: 'grey.100' }}>
+        Dashboard
+      </Link>
+    </div>
+  );
+}
+```
+
+To learn more about the supported props, visit:
+
+- Next.js related props: [Next.js Link](https://nextjs.org/docs/app/api-reference/components/link#props)
+- Material UI related props: [Material UI Link](/material-ui/react-link/)
+
+:::warning
+Do not use the Link from <b>`@mui/material-nextjs/*-pagesRouter`</b> for App Router.
+:::
+
 ## Pages Router
 
 This section walks through the Material UI integration with the Next.js [Pages Router](https://nextjs.org/docs/pages/building-your-application), for both [Server Side Rendering](https://nextjs.org/docs/pages/building-your-application/rendering/server-side-rendering) (SSR) and [Static Site Generation](https://nextjs.org/docs/pages/building-your-application/rendering/static-site-generation) (SSG).
@@ -149,3 +178,30 @@ If you are using TypeScript, add `DocumentHeadTagsProps` to the Document's props
    ...
  }
 ```
+
+### Link
+
+For pages router, use the Link only from `@mui/material-nextjs/*-pagesRouter`:
+
+```js
+import { Link } from '@mui/material-nextjs/v13-pagesRouter'; // or `v14-pagesRouter` if you are using Next.js v14
+
+function Nav() {
+  return (
+    <div>
+      <Link href="/dashboard" variant="caption" sx={{ bgcolor: 'grey.100' }}>
+        Dashboard
+      </Link>
+    </div>
+  );
+}
+```
+
+To learn more about the supported props, visit:
+
+- Next.js related props: [Next.js Link](https://nextjs.org/docs/pages/api-reference/components/link#props)
+- Material UI related props: [Material UI Link](/material-ui/react-link/)
+
+:::warning
+Do not use the Link from <b>`@mui/material-nextjs/*-appRouter`</b> for Pages Router.
+:::

packages/mui-material-nextjs/package.json

@@ -36,6 +36,9 @@
     "test": "cd ../../ && cross-env NODE_ENV=test mocha 'packages/mui-utils/**/*.test.{js,ts,tsx}'",
     "typescript": "tsc -p tsconfig.json"
   },
+  "dependencies": {
+    "clsx": "^2.1.0"
+  },
   "devDependencies": {
     "@emotion/cache": "^11.11.0",
     "@emotion/react": "^11.5.0",

packages/mui-material-nextjs/src/v13-appRouter/Link/Link.spec.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import { Link } from '@mui/material-nextjs/v13-appRouter';
+
+// @ts-expect-error href is required by Next.js
+<Link />;
+<Link href="" />;
+<Link
+  href={{
+    pathname: '/about',
+    query: { name: 'test' },
+  }}
+/>;
+<Link href="/dashboard" replace>
+  Dashboard
+</Link>;
+<Link href="/dashboard" scroll={false}>
+  Dashboard
+</Link>;
+<Link href="/dashboard" prefetch={false}>
+  Dashboard
+</Link>;
+
+<Link href="" sx={{ color: 'secondary.dark' }} />;
+<Link href="" variant="caption" />;
+<Link href="" underline="always" />;

packages/mui-material-nextjs/src/v13-appRouter/Link/Link.tsx

@@ -0,0 +1,63 @@
+'use client';
+import * as React from 'react';
+import clsx from 'clsx';
+import { usePathname } from 'next/navigation';
+import NextLink, { LinkProps as NextLinkProps } from 'next/link';
+import MuiLink, { LinkOwnProps as MuiLinkProps } from '@mui/material/Link';
+import linkClasses from './linkClasses';
+
+export interface LinkProps
+  extends Omit<NextLinkProps, 'passHref' | 'legacyBehavior'>,
+    MuiLinkProps {
+  /**
+   * Extra class name to apply to the link.
+   */
+  className?: string;
+  /**
+   * The active class name to apply when the current page is the same as the link's href.
+   * @default 'Mui-active'
+   */
+  activeClassName?: string;
+}
+
+const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(function Link(
+  {
+    href,
+    replace,
+    scroll,
+    shallow,
+    prefetch,
+    locale,
+    as,
+    className: classNameProp,
+    activeClassName = linkClasses.active,
+    ...muiLinkProps
+  },
+  ref,
+) {
+  const nextPathname = usePathname();
+  const pathname = typeof href === 'string' ? href : href.pathname;
+  const className = clsx(classNameProp, {
+    [activeClassName]: nextPathname === pathname && activeClassName,
+  });
+  return (
+    <NextLink
+      {...{
+        href,
+        replace,
+        scroll,
+        shallow,
+        prefetch,
+        locale,
+        as,
+      }}
+      // below props are required for NextLink to work with MUI Link
+      passHref
+      legacyBehavior
+    >
+      <MuiLink ref={ref} className={className} {...muiLinkProps} />
+    </NextLink>
+  );
+});
+
+export default Link;

packages/mui-material-nextjs/src/v13-appRouter/Link/index.ts

@@ -0,0 +1,4 @@
+export { default as Link } from './Link';
+export { default as linkClasses, getLinkUtilityClass } from './linkClasses';
+export type { LinkProps } from './Link';
+export type { LinkClasses } from './linkClasses';

packages/mui-material-nextjs/src/v13-appRouter/Link/linkClasses.ts

@@ -0,0 +1,26 @@
+import generateUtilityClasses from '@mui/utils/generateUtilityClasses';
+import generateUtilityClass from '@mui/utils/generateUtilityClass';
+import { LinkClasses as MuiLinkClasses } from '@mui/material/Link';
+
+export interface LinkClasses extends MuiLinkClasses {
+  /**
+   * Styles applied to the root element when the link is active.
+   */
+  active: string;
+}
+
+export function getLinkUtilityClass(slot: string): string {
+  return generateUtilityClass('MuiLink', slot);
+}
+
+const linkClasses: LinkClasses = generateUtilityClasses('MuiLink', [
+  'root',
+  'underlineNone',
+  'underlineHover',
+  'underlineAlways',
+  'button',
+  'focusVisible',
+  'active',
+]);
+
+export default linkClasses;

packages/mui-material-nextjs/src/v13-appRouter/index.ts

@@ -1,3 +1,4 @@
 'use client';
 export { default as AppRouterCacheProvider } from './appRouterV13';
 export * from './appRouterV13';
+export * from './Link';

packages/mui-material-nextjs/src/v13-pagesRouter/Link/Link.spec.tsx

@@ -0,0 +1,25 @@
+import * as React from 'react';
+import { Link } from '@mui/material-nextjs/v13-pagesRouter';
+
+// @ts-expect-error href is required by Next.js
+<Link />;
+<Link href="" />;
+<Link
+  href={{
+    pathname: '/about',
+    query: { name: 'test' },
+  }}
+/>;
+<Link href="/dashboard" replace>
+  Dashboard
+</Link>;
+<Link href="/dashboard" scroll={false}>
+  Dashboard
+</Link>;
+<Link href="/dashboard" prefetch={false}>
+  Dashboard
+</Link>;
+
+<Link href="" sx={{ color: 'secondary.dark' }} />;
+<Link href="" variant="caption" />;
+<Link href="" underline="always" />;

packages/mui-material-nextjs/src/v13-pagesRouter/Link/Link.tsx

@@ -0,0 +1,63 @@
+'use client';
+import * as React from 'react';
+import clsx from 'clsx';
+import { useRouter } from 'next/router';
+import NextLink, { LinkProps as NextLinkProps } from 'next/link';
+import MuiLink, { LinkOwnProps as MuiLinkProps } from '@mui/material/Link';
+import linkClasses from './linkClasses';
+
+export interface LinkProps
+  extends Omit<NextLinkProps, 'passHref' | 'legacyBehavior'>,
+    MuiLinkProps {
+  /**
+   * Extra class name to apply to the link.
+   */
+  className?: string;
+  /**
+   * The active class name to apply when the current page is the same as the link's href.
+   * @default 'Mui-active'
+   */
+  activeClassName?: string;
+}
+
+const Link = React.forwardRef<HTMLAnchorElement, LinkProps>(function Link(
+  {
+    href,
+    replace,
+    scroll,
+    shallow,
+    prefetch,
+    locale,
+    as,
+    className: classNameProp,
+    activeClassName = linkClasses.active,
+    ...muiLinkProps
+  },
+  ref,
+) {
+  const router = useRouter();
+  const pathname = typeof href === 'string' ? href : href.pathname;
+  const className = clsx(classNameProp, {
+    [activeClassName]: router.pathname === pathname && activeClassName,
+  });
+  return (
+    <NextLink
+      {...{
+        href,
+        replace,
+        scroll,
+        shallow,
+        prefetch,
+        locale,
+        as,
+      }}
+      // below props are required for NextLink to work with MUI Link
+      passHref
+      legacyBehavior
+    >
+      <MuiLink ref={ref} className={className} {...muiLinkProps} />
+    </NextLink>
+  );
+});
+
+export default Link;

packages/mui-material-nextjs/src/v13-pagesRouter/Link/index.ts

@@ -0,0 +1,4 @@
+export { default as Link } from './Link';
+export { default as linkClasses, getLinkUtilityClass } from './linkClasses';
+export type { LinkProps } from './Link';
+export type { LinkClasses } from './linkClasses';

packages/mui-material-nextjs/src/v13-pagesRouter/Link/linkClasses.ts

@@ -0,0 +1,26 @@
+import generateUtilityClasses from '@mui/utils/generateUtilityClasses';
+import generateUtilityClass from '@mui/utils/generateUtilityClass';
+import { LinkClasses as MuiLinkClasses } from '@mui/material/Link';
+
+export interface LinkClasses extends MuiLinkClasses {
+  /**
+   * Styles applied to the root element when the link is active.
+   */
+  active: string;
+}
+
+export function getLinkUtilityClass(slot: string): string {
+  return generateUtilityClass('MuiLink', slot);
+}
+
+const linkClasses: LinkClasses = generateUtilityClasses('MuiLink', [
+  'root',
+  'underlineNone',
+  'underlineHover',
+  'underlineAlways',
+  'button',
+  'focusVisible',
+  'active',
+]);
+
+export default linkClasses;

packages/mui-material-nextjs/src/v13-pagesRouter/index.ts

@@ -1,2 +1,3 @@
 export * from './pagesRouterV13Document';
 export * from './pagesRouterV13App';
+export * from './Link';

packages/mui-material-nextjs/tsconfig.build.json

@@ -11,5 +11,6 @@
     "rootDir": "./src"
   },
   "include": ["./src/**/*.ts*"],
-  "exclude": ["src/**/*.spec.ts*", "src/**/*.test.ts*"]
+  "exclude": ["src/**/*.spec.ts*", "src/**/*.test.ts*"],
+  "references": [{ "path": "../mui-material/tsconfig.build.json" }]
 }