DocsBlog

  • 1.0.0

  • light

    dark

    system

    Switch mode

  • Cerberus

    Acheron

    Elysium

Get Started
Components
Data Grid
Styling
Theming

Overview

Get StartedInstallationFAQContributing

AI

LLMS.txt

Installation

A step-by-step guide to install Cerberus

Setup Guide

For a better developer experience, we recommend using either Deno or pnPm as your package manager which has first class support for JSR packages.

You can still use NPM, it will just require a bit more configuration.

Step 1 - Setup Panda CSS

Before you can use the Cerberus, you need to have Panda CSS installed and setup in your project. This is the preferred style engine for Cerberus.

Head over to the Panda CSS installation guide to get started.

Note

We recommend using the App Router for your Next.js project. The Pages Router (deprecated) has some known issues regarding atomic css generation.

Step 2 - Setup the Cerberus Preset

Now that Panda is installed, you need to install the Cerberus preset package. We publish as many packages to JSR as possible to ensure a better experience for developers.

Terminal
Copy
npx jsr add @cerberus/panda-preset
Terminal
Copy
pnpm add jsr:@cerberus/panda-preset
Terminal
Copy
deno add jsr:@cerberus/panda-preset
Terminal
Copy
bunx jsr add @cerberus/panda-preset

Next, update your PandaCSS config to utilize the Cerberus helpers:

import {
  createCerberusConfig,
  createCerberusPreset,
} from '@cerberus/panda-preset'

export default createCerberusConfig({
  presets: [createCerberusPreset()],

  include: [
    './app/**/*.{ts,tsx}'
  ],
  exclude: [],
})

The createCerberusConfig function adds the required Cerberus config settings to PandaCSS along with any additional settings you pass into it.

The createCerberusPreset function does the same except on the preset level.

The core preset comes with the base "cerberus" theme and PandaCSS presets built in:

  • Core Preset: Non-semantic tokens theme contents (recipes, utilities, conditions, etc.)
  • PandaCSS Preset: The required PandaCSS preset needed when customizing presets
  • Cerberus Theme Preset: The Cerberus theme

Note

If you are using the panda-preset there is no need to install the additional PanaCSS base presets. The core preset will set everything up on your behalf.

Step 3 - Setup Fonts

The Cerberus core preset includes a set of font helpers. In order to utilize them, your project needs to have your preferred fonts assigned to the following CSS variables:

  • --font-display: Any display heading text-style
  • --font-sans: Any other text style
  • --font-mono: Any monospace text style

If using NextJS fonts, you can simply import and assign these with the fonts package:

import { Poppins, Recursive } from 'next/font/google'

  const poppins = Poppins({
    display: 'swap',
    subsets: ['latin'],
    weight: ['400', '600', '700'],
    variable: '--font-sans',
  })
  const recursive = Recursive({
    display: 'swap',
    subsets: ['latin'],
    weight: ['400'],
    variable: '--font-mono',
  })

Step 4 - Update your root layout to initiate Cerberus

Because Cerberus provides multiple themes and modes out of the box, you need to initialize your root layout to trigger the default options you want to use.

To connect the Cerberus theme, add the required data attributes to your root html tag.

function RootLayout({ children }) {
    return (
      <html lang="en" data-panda-theme="cerberus" data-color-mode="light">
        <body>{children}</body>
      </html>
    )
  }

Important: This is a good point to run the panda codegen command to generate the Cerberus related additions.

Once this has been run, you can start using Cerberus styles and themes in your project. If you are interested in using the React library, continue

Using React

To add the React library to your project, continue in the guide.

Note

The React library requires the Panda-Preset to be setup in order to use.

Step 1 - Update Path Aliases

Cerberus React assumes the baseUrl is setup to the root location in your tsconfig.json file.

If you do not, or use a different location, you should include a path alias for the styled-system/* location. Not doing so will result in build errors.

// tsconfig.json
  {
    "compilerOptions": {
      "baseUrl": ".",
      // ...your config options
    }
  }

Note

If using Deno, simply setup your import map to include the styled-system/\* alias.

Step 2 - Install Cerberus React

Now that your base path is setup, you can install Cerberus React.

Terminal
Copy
npm install @cerberus/react@npm:@cerberus-design/react
Terminal
Copy
pnpm add @cerberus/react@npm:@cerberus-design/react
Terminal
Copy
deno add npm:@cerberus-design/react
Terminal
Copy
bun add @cerberus/react@npm:@cerberus-design/react

Note

In the snippet above, we are simply creating an alias path for NPM to use of the name we prefer. For Deno users, we recommend adding an alias to your import map for consistency.

Update your panda.config.ts

Add the build config to the include array so Panda can generate the styles.

import { createCerberusConfig, createCerberusPreset } from "@cerberus/panda-preset";

  export default createCerberusConfig({
    // ...your previous settings

    include: [
      "./node_modules/@cerberus/react/dist/panda.buildinfo.json",
      "./app/**/*.{ts,tsx,js,jsx}",
    ],
  });

Step 3 - Use the Cerberus Context Provider

In order for components to have access to icons, you must wrap your application with the CerberusProvider context.


At this point, you are ready to start using Cerberus React.

Optional - Registering Custom Icons

React comes built in with the Carbon Icons set. However, if you prefer a different icon library, you can register it with Cerberus Context Provider.

Learn how to register custom icons with the Cerberus Context Provider

Optional - Multi-theme support

If you want to support multiple themes, you can use the presetAcheronTheme and getThemeName helpers to configure your theme.

import { createCerberusConfig, createCerberusPreset } from "@cerberus/panda-preset";
  import { presetAcheronTheme, getThemeName } from "@cerberus/preset-acheron-theme";

  export default createCerberusConfig({
    clean: true,
    preflight: true,

    presets: [createCerberusPreset(), presetAcheronTheme],

    include: [
      "./node_modules/@cerberus/react/dist/panda.buildinfo.json",
      "./app/**/*.{ts,tsx,js,jsx}",
    ],

    staticCss: {
      themes: ["cerberus", getThemeName()],
    },
  });

Tip: Add a Cerberus script

To help make maintaining a breeze, add these scripts to your package.json to use when you need to upgrade Cerberus:

"scripts": {
  "up:cerby:npm-deps": "pnpm install @cerberus/react@npm:@cerberus-design/react@latest",
  "up:cerby:jsr-deps": "pnpm add jsr:@cerberus/panda-preset && pnpm add jsr:@cerberus/preset-acheron-theme",
  "up:cerberus": "pnpm run up:cerby:npm-deps && pnpm run up:cerby:jsr-deps && pnpm up @pandacss/dev@latest"
}

Now you can update Cerberus and PandaCSS with a single command:

Terminal
Copy
npm run up:cerberus
Terminal
Copy
pnpm run up:cerberus
Terminal
Copy
deno run npm:up:cerberus
Terminal
Copy
bun run up:cerberus

On this page

  • Edit this page on Github
Cerberus Design System | Docs
'use client'

import { CerberusProvider } from '@cerberus/react'
import { type PropsWithChildren } from 'react'

export function CerberusConfig(props: PropsWithChildren) {
  return <CerberusProvider>{props.children}</CerberusProvider>
}