--- title: Next.js (Pages) description: "A guide for installing and using Yamada UI with Next.js pages directory." --- ## Installation ### Create application Create Next.js application. ```bash pnpm create next-app my-app --typescript ``` ```bash npx create-next-app my-app --typescript ``` ```bash yarn create next-app my-app --typescript ``` ```bash bun create next-app my-app --typescript ``` ### Setup Running the command will create the necessary files and folders in your project. ```bash pnpm dlx @yamada-ui/cli init ``` ```bash npx @yamada-ui/cli init ``` ```bash yarn dlx @yamada-ui/cli init ``` ```bash bunx @yamada-ui/cli init ``` ### Install the package Install `@workspaces/ui` to your application. ```bash pnpm add "@workspaces/ui@workspace:*" ``` ```bash npm install "@workspaces/ui@workspace:*" ``` ```bash yarn add "@workspaces/ui@workspace:*" ``` ```bash bun add "@workspaces/ui@workspace:*" ``` ### Add provider After installing, add `UIProvider` to the root of your application. ```tsx import { UIProvider } from "@workspaces/ui" import type { AppProps } from "next/app" export default function App({ Component, pageProps }: AppProps) { return ( ) } ``` ### Use components After adding `UIProvider`, you can use the components in your application. ```tsx import { Button } from "@workspaces/ui" export default function Home() { return } ``` That's it! You've successfully set up Yamada UI. ## Scripts ### ColorModeScript To use [Color Mode](https://yamada-ui.com/docs/theming/color-mode.md), you need to add `ColorModeScript` to the `body` to ensure it works correctly. This is because color mode is implemented using `localStorage` or `cookies`, and adding the script ensures proper synchronization when the page loads. #### Add Script ```tsx import { Html, Head, Main, NextScript } from "next/document" import { ColorModeScript } from "@workspaces/ui" export default function Document() { return (
) } ``` If you change the `defaultColorMode` in your [config](https://yamada-ui.com/docs/theming/configuration/overview.md), set the `defaultValue` prop on `ColorModeScript`. ```tsx import { Html, Head, Main, NextScript } from "next/document" import { ColorModeScript } from "@workspaces/ui" import { config } from "@workspace/theme" export default function Document() { return (
) } ``` #### Add getServerSideProps To share `getServerSideProps` across multiple pages, define `getServerSideSharedProps`. ```tsx import { GetServerSidePropsContext } from "next" export const getServerSideSharedProps = ({ req, }: GetServerSidePropsContext) => { return { props: { cookies: req.headers.cookie ?? "", }, } } ``` ```tsx import { getServerSideSharedProps } from "@/get-server-side-props" import { Button } from "@workspaces/ui" export const getServerSideProps = getServerSideSharedProps export default function Home() { return } ``` #### Update Provider ```tsx import { UIProvider } from "@workspaces/ui" import type { AppProps } from "next/app" export default function App({ Component, pageProps }: AppProps) { const { cookie } = pageProps return ( ) } ``` ### ThemeSchemeScript To use [theme switching](https://yamada-ui.com/docs/theming/switching-themes.md), you need to add `ThemeSchemeScript` to the `body` to ensure it works correctly. This is because theme switching is implemented using `localStorage` or `cookies`, and adding the script ensures proper synchronization when the page loads. #### Add Script ```tsx import { Html, Head, Main, NextScript } from "next/document" import { ThemeSchemeScript } from "@workspaces/ui" export default function Document() { return (
) } ``` If you change the `defaultThemeScheme` in your [config](https://yamada-ui.com/docs/theming/configuration/overview.md), set the `defaultValue` prop on `ThemeSchemeScript`. ```tsx import { Html, Head, Main, NextScript } from "next/document" import { ThemeSchemeScript } from "@workspaces/ui" import { config } from "@workspace/theme" export default function Document() { return (
) } ``` #### Add getServerSideProps To share `getServerSideProps` across multiple pages, define `getServerSideSharedProps`. ```tsx import { GetServerSidePropsContext } from "next" export const getServerSideSharedProps = ({ req, }: GetServerSidePropsContext) => { return { props: { cookies: req.headers.cookie ?? "", }, } } ``` ```tsx import { getServerSideSharedProps } from "@/get-server-side-props" import { Button } from "@workspaces/ui" export const getServerSideProps = getServerSideSharedProps export default function Home() { return } ``` #### Update Provider ```tsx import { UIProvider } from "@workspaces/ui" import type { AppProps } from "next/app" export default function App({ Component, pageProps }: AppProps) { const { cookie } = pageProps return ( ) } ``` ## Component Integration You can integrate Next.js components such as [Link](https://nextjs.org/docs/pages/api-reference/components/link) and [Image](https://nextjs.org/docs/pages/api-reference/components/image) with Yamada UI components. ### Link ```tsx import type { ButtonProps, HTMLRefAttributes, IconButtonProps, LinkProps, Merge, } from "@yamada-ui/react" import type { LinkProps as OriginalLinkProps } from "next/link" import type { FC } from "react" import { Button, IconButton, Link } from "@yamada-ui/react" import OriginalLink from "next/link" export interface NextLinkProps extends Omit< Merge, "as" | "ref" > {} export const NextLink: FC = (props) => { return } export interface NextLinkButtonProps extends Omit, "as" | "ref">, HTMLRefAttributes<"a"> {} export const NextLinkButton: FC = (props) => { return