Overview

The Cerberus Panda CSS Preset adds a set of core features to the Cerberus Design System.

Prerequisites - Setting up Panda CSS

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

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

Step 1 - Install Panda CSS Preset

In order to use the Cerberus Panda Preset, you need to install the PandaCSS preset package.

Install Cerberus core packages

Install the Cerberus core packages, with the package manager of your choice:

Step 2 - Setup Cerberus

Update the Panda Configuration

Once you have installed and setup Panda CSS and added the Cerberus Panda Preset, you need to update your Panda configuration to include the Cerberus Panda Preset.

panda.config.ts
import { defineConfig } from '@pandacss/dev'
import pandaPreset from '@pandacss/preset-panda'
import { cerberusPreset, cerberusConfig } from '@cerberus/panda-preset'


export default defineConfig({
  ...cerberusConfig,


  include: [
    './node_modules/@cerberus/react/src/**/*.{ts,tsx}',
    './app/**/*.{ts,tsx,js,jsx}', // <- Make sure this path is to your project
  ],
  exclude: [],


  presets: [pandaPreset, cerberusPreset],
})

Update your local styles

Now that you have extended Panda, you need to update your local styles by running the prepare script.

Step 4 - Connect the Cerberus Theme

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

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

Step 5 - Setup Cerberus Fonts (optional)

If you would like to use the Brand font associated with Cerberus, we recommend Poppins. Unfortunately, it is not a variable font, so another great solution which is, is the Inter font (comes pre-configured in NextJS apps).

NextJS usage:

app/layout.tsx
import { Poppins, Recursive } from 'next/font/google'


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)}
      lang="en"
      data-panda-theme="cerberus"
      data-color-mode="light"
    >
      <body>
        {props.children}
      </body>
    </html>
  )
}

Using Cerberus React

If you are interested in using the Cerberus React, install it now along with your Icon library of choice:

Using Icons

Cerberus is icon agnostic which means you need to register the library you prefer. Cerberus was built with Carbon Icons in mind.

If you prefer to use Cerberus Icons, you can install them now:

Setting up Cerberus React

To use Cerberus React, you need to create a new file to wrap your application with the CerberusProvider where you will keep your global settings.

context/cerberus-config.tsx
'use client'


import {
  CerberusProvider,
  defineIcons,
  makeSystemConfig,
} from '@cerberus-design/react'
import {
  Calendar,
  Checkmark,
  CheckmarkOutline,
  ChevronDown,
  ChevronLeft,
  ChevronRight,
  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 has to be used
 * in a client abstraction because of R19 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,
  promptModal: Information,
  waitingFileUploader: CloudUpload,
  infoNotification: Information,
  successNotification: CheckmarkOutline,
  warningNotification: WarningAlt,
  dangerNotification: WarningFilled,
  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:

app/layout.tsx
import { Poppins, Recursive } from 'next/font/google'
import { type PropsWithChildren } from 'react'
import { css, cx } from '@cerberus/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 async function RootLayout(props: PropsWithChildren<RootProps>) {
  return (
    <html
      className={cx(poppins.variable, recursive.variable)}
      lang="en"
    >
      <body
        className={css({
          minW: '18.75rem',
          h: 'full',
        })}
      >
        <CerberusConfig>
          {props.children}
        </CerberusConfig>
      </body>
    </html>
  )
}

Add a Cerberus script

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

package.json
"scripts": {
  "up:cerberus": "pnpm up @cerberus/{styled-system,react}@latest && pnpm dlx jsr add @cerberus/panda-preset"
}

FAQ

Why does the version paths the react & styled-system look weird?

The Cerberus packages are published under the @cerberus-design organization in NPM (due to the name cerberus being taken). However, in JSR, we use the @cerberus organization. We eventually plan on fully migrating to JSR when there is better support for the features we need.

The version paths are simply creating an alias to the @cerberus-design organization so that you can have consistent package naming across your project.

Everything should use the @cerberus organization in your code.

Why do I need to add the @cerberus/styled-system package?

The @cerberus/styled-system package is a dependency of the Cerberus Panda Preset. It is a styled-system that is pre-configured to work with the Cerberus Design System and creates a single source of truth for our UI related packages.