Next.js (Pages)

A guide for installing and using Yamada UI with Next.js pages directory.

Installation

  • 1

    Create application

    Create Next.js application.

    pnpm create next-app my-app --typescript
  • 2

    Setup

    Running the command will create the necessary files and folders in your project.

    pnpm dlx @yamada-ui/cli init
  • 3

    Install the package

    Install @workspaces/ui to your application.

    pnpm add "@workspaces/ui@workspace:*"
  • 4

    Add provider

    After installing, add UIProvider to the root of your application.

    _app.tsx

    import { UIProvider } from "@workspaces/ui"
import type { AppProps } from "next/app"

export default function App({ Component, pageProps }: AppProps) {
  return (
    <UIProvider>
      <Component {...pageProps} />
    </UIProvider>
  )
}
  • 5

    Use components

    After adding UIProvider, you can use the components in your application.

    index.tsx

    import { Button } from "@workspaces/ui"

export default function Home() {
  return <Button>Click me!</Button>
}

    That's it! You've successfully set up Yamada UI.

Scripts

ColorModeScript

To use Color Mode, 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.

  • 1

    Add Script

    _document.tsx

    import { Html, Head, Main, NextScript } from "next/document"
import { ColorModeScript } from "@workspaces/ui"

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        <ColorModeScript type="cookie" />

        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

    If you change the defaultColorMode in your config, set the defaultValue prop on ColorModeScript.

    _document.tsx

    import { Html, Head, Main, NextScript } from "next/document"
import { ColorModeScript } from "@workspaces/ui"
import { config } from "@workspace/theme"

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        <ColorModeScript type="cookie" defaultValue={config.defaultColorMode} />

        <Main />
        <NextScript />
      </body>
    </Html>
  )
}
  • 2

    Add getServerSideProps

    To share getServerSideProps across multiple pages, define getServerSideSharedProps.

    get-server-side-props.ts

    import { GetServerSidePropsContext } from "next"

export const getServerSideSharedProps = ({
  req,
}: GetServerSidePropsContext) => {
  return {
    props: {
      cookies: req.headers.cookie ?? "",
    },
  }
}

    index.tsx

    import { getServerSideSharedProps } from "@/get-server-side-props"
import { Button } from "@workspaces/ui"

export const getServerSideProps = getServerSideSharedProps

export default function Home() {
  return <Button>Click me!</Button>
}
  • 3

    Update Provider

    _app.tsx

    import { UIProvider } from "@workspaces/ui"
import type { AppProps } from "next/app"

export default function App({ Component, pageProps }: AppProps) {
  const { cookie } = pageProps

  return (
    <UIProvider cookie={cookie}>
      <Component {...pageProps} />
    </UIProvider>
  )
}

ThemeSchemeScript

To use theme switching, 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.

  • 1

    Add Script

    _document.tsx

    import { Html, Head, Main, NextScript } from "next/document"
import { ThemeSchemeScript } from "@workspaces/ui"

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        <ThemeSchemeScript type="cookie" />

        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

    If you change the defaultThemeScheme in your config, set the defaultValue prop on ThemeSchemeScript.

    _document.tsx

    import { Html, Head, Main, NextScript } from "next/document"
import { ThemeSchemeScript } from "@workspaces/ui"
import { config } from "@workspace/theme"

export default function Document() {
  return (
    <Html lang="en">
      <Head />
      <body>
        <ThemeSchemeScript
          type="cookie"
          defaultValue={config.defaultColorMode}
        />

        <Main />
        <NextScript />
      </body>
    </Html>
  )
}
  • 2

    Add getServerSideProps

    To share getServerSideProps across multiple pages, define getServerSideSharedProps.

    get-server-side-props.ts

    import { GetServerSidePropsContext } from "next"

export const getServerSideSharedProps = ({
  req,
}: GetServerSidePropsContext) => {
  return {
    props: {
      cookies: req.headers.cookie ?? "",
    },
  }
}

    index.tsx

    import { getServerSideSharedProps } from "@/get-server-side-props"
import { Button } from "@workspaces/ui"

export const getServerSideProps = getServerSideSharedProps

export default function Home() {
  return <Button>Click me!</Button>
}
  • 3

    Update Provider

    _app.tsx

    import { UIProvider } from "@workspaces/ui"
import type { AppProps } from "next/app"

export default function App({ Component, pageProps }: AppProps) {
  const { cookie } = pageProps

  return (
    <UIProvider cookie={cookie}>
      <Component {...pageProps} />
    </UIProvider>
  )
}