Getting Started with Nextjs
A guide for installing Saas UI with Nextjs projects
1. Installation#
In your Next.js project, install Saas UI by running either of the following:
npm i @saas-ui/react @chakra-ui/react @chakra-ui/next-js @emotion/react@^11 @emotion/styled@^11 framer-motion@^6
yarn add @saas-ui/react @chakra-ui/react @chakra-ui/next-js @emotion/react@^11 @emotion/styled@^11 framer-motion@^6
2. Provider Setup#
After installing Saas UI, you need to set up the SaasProvider
at the root
of your application. If you already have ChakraProvider
in your app, you can replace this with SaasProvider
.
Go to pages/_app.js
or pages/_app.tsx
(create it if it doesn't exist) and
wrap the Component
with the SaasProvider
:
// pages/_app.jsimport { SaasProvider } from '@saas-ui/react'function MyApp({ Component, pageProps }) {return (<SaasProvider><Component {...pageProps} /></SaasProvider>)}export default MyApp
3. Link Component#
Configure a linkComponent
to make the Saas UI Link
works with the Next.js router.
import Link, { LinkProps } from 'next/link'import { SaasProvider } from '@saas-ui/react'const NextLink = React.forwardRef<HTMLAnchorElement, LinkProps>((props, ref) => <Link ref={ref} {...props} />)function MyApp({ Component, pageProps }) {return (<SaasProvider linkComponent={Link}><Component {...pageProps} /></SaasProvider>)}
App Directory Setup#
Next.js 13 introduces a new app/
directory / folder structure. By default it
uses Server Components. However, Saas UI only works in client-side
components.
To use Saas UI in server components, you need to convert them into client-side
component by adding a 'use client';
at the top of your file.
Chakra UI also provides a @chakra-ui/next-js
package that gives you a smoother
experience when using Saas UI in the app directory.
This package provides the CacheProvider which composes the Emotion.js' cache
provider with the useServerInsertedHTML
hook from next/navigation. This is
necessary to ensure that computed styles are included in the initial server
payload (during streaming).
To use Saas UI in app directory, you can wrap SaasProvider
and CacheProvider
in your own client Component.
// app/providers.tsx'use client'import { CacheProvider } from '@chakra-ui/next-js'import { SaasProvider } from '@saas-ui/react'export function Providers({ children }: { children: React.ReactNode }) {return (<CacheProvider><SaasProvider>{children}</SaasProvider></CacheProvider>)}
Now, you can import and render <Providers />
directly within your root. With the providers rendered at the root, all the components and hooks will work as expected within your own Client Components.
// app/layout.tsximport { Providers } from './providers'export default function RootLayout({children,}: {children: React.ReactNode,}) {return (<html lang="en"><body><Providers>{children}</Providers></body></html>)}
The
'use client'
directive is still required to be added to the top of the page-related file.
If you're not using the new app/
directory, there's no need to add
the'use client';
directive add the top of your file.
4. Customizing Theme#
If you intend to customise the default theme object to match your design
requirements, you can extend the theme
from @chakra-ui/react
.
Chakra UI provides an extendTheme
function that deep merges the default theme
with your customizations.
// 1. Import the extendTheme functionimport { extendTheme } from '@chakra-ui/react'// 2. Import the Saas UI themeimport { SaasProvider, theme as baseTheme } from '@saas-ui/react'// 2. Extend the theme to include custom colors, fonts, etcconst colors = {brand: {900: '#1a365d',800: '#153e75',700: '#2a69ac',},}const theme = extendTheme({ colors }, baseTheme)// 3. Pass the `theme` prop to the `SaasProvider`function MyApp({ Component, pageProps }) {return (<SaasProvider theme={theme}><Component {...pageProps} /></SaasProvider>)}
To further customize components or build your own design system, the
theme-tools
package includes useful utilities.
6. Color Mode Script#
The color mode script needs to be added before the content inside the body
tag
for local storage syncing to work correctly.
When setting the initial color mode, we recommend adding it as a config to your theme and reference that in the
ColorModeScript
.
To use
ColorModeScript
on a site with strictContent-Security-Policy
, you can use thenonce
prop that will be passed to the<script>
tag.
// pages/_document.jsimport { ColorModeScript } from '@chakra-ui/react'import NextDocument, { Html, Head, Main, NextScript } from 'next/document'import theme from './theme'export default class Document extends NextDocument {render() {return (<Html lang="en"><Head /><body>{/* 👇 Here's the script */}<ColorModeScript initialColorMode={theme.config.initialColorMode} /><Main /><NextScript /></body></Html>)}}
Notes on TypeScript 🚨#
Please note that when adding Chakra UI to a TypeScript project, a minimum
TypeScript version of 4.1.0
is required.
Was this helpful?