Customization

Learn how to customize Cerberus to suit your needs.

Cerberus is a highly customizable library that allows you to define your own rules and configurations. This page will guide you through the process of customizing Cerberus to suit your needs.

Which Option Should I Choose?

  • Use global config when:
  • Create your own design system
  • You need low-level control over your settings
  • Use component level when:
  • Create one-off component style changes
  • Build your own custom components

Option 1: Global Configuration

This is the most flexible way to customize Cerberus. You can define your own design system and pass it to Cerberus via PandaCSS.

Extending the PandaCSS configuration

You can extend the PandaCSS configuration by adding your own custom properties.

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


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


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

Extending the Cerberus Preset

You can add global customizations by extending the Cerberus preset.

panda.config.ts
import {
  createCerberusConfig,
  createCerberusPreset,
} from '@cerberus/panda-preset'
import { customButtonRecipe } from './system/recipes/button'


export default createCerberusConfig({
  clean: true,
  presets: [createCerberusPreset({
    sansFont: 'Poppins',
    monoFont: 'Recursive',
  })],


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

Option 2: Component-Specific Configuration

This is the easiest way to customize Cerberus. You simply just add custom styles to a component in Cerberus.

Customizing a Button
import { Button, type ButtonProps } from '@cerberus/react'
import { css } from 'styled-system'


export function CustomButton(props: ButtonProps) {
  return (
    <Button
      {...props}
      className={css({
        backgroundColor: 'red',
        color: 'white',
        borderRadius: '8px',
      })}
    />
  )
}

Customizing Icons

Some components in Cerberus use icons. You can customize these icons by providing your own icon components.

In your entry file, call defineIcons with an object that maps icon names to icon components.

The following code replaces all instances of the invalid icon with a custom Lucide icon.

app/layout.tsx
import { defineIcons } from '@cerberus/react'
import { cx } from 'styled-system/css'
import { Poppins, Recursive } from 'next/font/google'
import { type PropsWithChildren } from 'react'
import { CircleAlert } from 'lucide-react';


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',
})


defineIcons({
  invalid: CircleAlert,
})


interface RootProps {}


export default async 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>
  )
}

API

The defineIcons function takes an object that maps icon names to icon components.

export type IconType = CarbonIconType | ElementType


export interface DefinedIcons<T extends IconType = IconType> {
  accordionIndicator: T
  avatar: T
  calendar: T
  calendarPrev: T
  calendarNext: T
  checkbox?: T
  close: T
  confirmModal: T
  delete: T
  promptModal: T
  waitingFileUploader: T
  fileUploader?: T
  indeterminate?: T
  infoNotification: T
  successNotification: T
  warningNotification: T
  dangerNotification: T
  invalid: T
  invalidAlt: T
  redo: T
  selectArrow: T
  selectChecked: T
  toggleChecked: T
}

On this page