Getting Started

A step-by-step guide to get started with Cerberus Design System

What is Cerberus?

Cerberus is a UI-like flexible design system that is built on top of Panda CSS. It uses two foundational packages:

Panda Preset
React

The Cerberus Panda Preset is a set of tokens, recipes, conditions, utilities, patterns, and more that are built on top of Panda CSS. It provides a consistent look and feel for your application and makes it easy to get started with Panda CSS.

Cerberus React

The Cerberus React is a set of pre-configured components that are built on top of the Panda CSS preset. It provides a set of components that can be categorized into 3 groups:

Abstractions - Abstracted component APIs of the primitives
Primitives - Low level component APIs for fine-grained control
Parts - Object oriented components that are used to build the abstractions

Setup Guide

Step 1 - Setup Panda CSS

Before you can use the Cerberus, you need to have Panda CSS installed and setup in your project.

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

Step 2 - Setup the Cerberus Preset

In order to use the Cerberus React, you need to install the Cerberus preset package.

Terminal

npx jsr add @cerberus/panda-preset

Terminal

pnpm dlx jsr add @cerberus/panda-preset

Terminal

npx 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: [
    './node_modules/@cerberus/react/**/*.{ts,tsx,js,jsx}', // track @cerberus/react components
    './app/**/*.{ts,tsx}'
  ],
  exclude: [],
})

The createCerberusConfig function adds the recommended Cerberus settings and any additional settings you pass into it.

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

Step 3 - Update your root layout to trigger 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>
  )
}

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

Path Aliases

Cerberus React assumes you have your baseUrl 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.

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  }
}

Step 4 - Setup Cerberus React

Cerberus React is icon agnostic which means you should install the Icon library of choice before installing the Cerberus React package.

Terminal

npm install @cerberus/react@npm:@cerberus-design/react

Terminal

pnpm add @cerberus/react@npm:@cerberus-design/react

Terminal

yarn add @cerberus/react@npm:@cerberus-design/react

Step 5 - Registering Your Icons

Because Cerberus React is icon agnostic, you need to register the library you prefer. This will map certain icons to the Cerberus components that depend on them.

If you do not have an icon preference, we recommend using the Carbon Icons library.

Terminal

npm install @carbon/icons-react

Terminal

pnpm add @carbon/icons-react

Terminal

yarn add @carbon/icons-react

Create your Cerberus Config

In Next, you will need to create a new file to wrap your application with the CerberusProvider where you will keep your global settings.

We will name this abstraction CerberusConfig since it will own the Cerberus configuration.

'use client'

import {
  CerberusProvider,
  defineIcons,
  makeSystemConfig,
} from '@cerberus/react'
import {
  Calendar,
  Checkmark,
  CheckmarkOutline,
  ChevronDown,
  ChevronLeft,
  ChevronRight,
  ChevronUp,
  Close,
  CloudUpload,
  Information,
  Restart,
  TrashCan,
  UserFilled,
  Warning,
  WarningAlt,
  WarningFilled,
} from '@carbon/icons-react'
import type { PropsWithChildren } from 'react'

/**
 * This module provides a Cerberus configuration component which must to be used
 * in a client abstraction because of React 19 rules around data passing into
 * props.
 */

const icons = defineIcons({
  accordionIndicator: ChevronDown,
  avatar: UserFilled,
  calendar: Calendar,
  calendarPrev: ChevronLeft,
  calendarNext: ChevronRight,
  close: Close,
  confirmModal: Information,
  delete: TrashCan,
  decrement: ChevronDown,
  promptModal: Information,
  waitingFileUploader: CloudUpload,
  infoNotification: Information,
  successNotification: CheckmarkOutline,
  warningNotification: WarningAlt,
  dangerNotification: WarningFilled,
  increment: ChevronUp,
  invalid: WarningFilled,
  invalidAlt: Warning,
  redo: Restart,
  selectArrow: ChevronDown,
  selectChecked: Checkmark,
  toggleChecked: Checkmark,
})

const config = makeSystemConfig({
  icons,
})

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

Then wrap your application with the CerberusConfig component:

import { Poppins, Recursive } from 'next/font/google'
import { type PropsWithChildren } from 'react'
import { css, cx } from 'styled-system/css'
import CerberusConfig from '@/context/cerberus-config'

import './globals.css'

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

interface RootProps {}

export default function RootLayout(props: PropsWithChildren<RootProps>) {
  return (
    <html
      className={cx(poppins.variable, recursive.variable)}
      data-panda-theme="cerberus"
      data-color-mode="light"
      lang="en"
    >
      <body>
        <CerberusConfig>
          {props.children}
        </CerberusConfig>
      </body>
    </html>
  )
}

Tip: Add a Cerberus script

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

"scripts": {
  "up:cerberus": "pnpm up @cerberus/react@latest && pnpm dlx jsr add @cerberus/panda-preset && pnpm up @pandacss/dev@latest"
}

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

Terminal

npm run up:cerberus

Terminal

pnpm run up:cerberus

Terminal

yarn run up:cerberus

On this page

Edit this page on Github