Documentation
Next.js 13
Next.js 13 introduces a new app/ directory folder structure. By default it uses React Server Components. To use NextUI in those components, you need to convert them into client-side component by adding a
'use client'; at the top of your file.
NextUI only works in client-side components.
Next.js 12 and below
If you're not using the new app/ directory, there's no need to add the 'use client'; directive, you just need to customize the _app.jsx entry file to load the provider. Here's an example project.
SSR Setup
In Next.js framework, you need to customize the pages/_document.js file. Then we add the following code to the file:
// pages/_document.js import React from "react"; import Document, { Html, Head, Main, NextScript } from "next/document"; import { CssBaseline } from "@nextui-org/react"; class MyDocument extends Document { static async getInitialProps(ctx) { const initialProps = await Document.getInitialProps(ctx); return { ...initialProps, styles: React.Children.toArray([initialProps.styles]), }; } render() { return ( <Html lang="en"> <Head>{CssBaseline.flush()}</Head> <body> <Main /> <NextScript /> </body> </Html> ); } } export default MyDocument;
Provider Setup
NextUI needs to be wrapped in a provider to work properly. You need to set up the NextUIProvider at the root of your application.
Go to pages/_app.js or pages/_app.tsx (create it if it doesn't exist) and add the following code:
// pages/_app.js // 1. import `NextUIProvider` component import { NextUIProvider } from '@nextui-org/react' function MyApp({ Component, pageProps }) { // 2. Use at the root of your app return ( <NextUIProvider> <Component {...pageProps} /> </NextUIProvider> ) } export default MyApp
Customizing theme
If you intend to customize the default theme object to match your design requirements, you need to extend the theme.
NextUI provides a createTheme function that deep merges the default theme with your customizations.
// pages/_app.js // 1. Import `createTheme` import { createTheme, NextUIProvider } from "@nextui-org/react" // 2. Call `createTheme` and pass your custom theme values const theme = createTheme({ type: "dark", // it could be "light" or "dark" theme: { colors: { primary: '#4ADE7B', secondary: '#F9CB80', error: '#FCC5D8', }, } }) // 3. Pass the new `theme`` to the `NextUIProvider` function MyApp({ Component, pageProps }) { return ( <NextUIProvider theme={theme}> <Component {...pageProps} /> </NextUIProvider> ) } export default MyApp
To further customize the theme, please refer to the theming documentation.
