# Cerberus UI Platform Documentation

> Index of all docs: /llms.txt

---
## accordion

---
title: Accordion
description: A way to show and hide information by sections.
npm: '@cerberus-design/react'
source: 'components/accordion'
recipe: 'slots/accordion.ts'
ark: 'accordion'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The Accordion component is a controlled abstraction of the primitive components that can be used to show or hide content. It can be used in a group with other accordion items to allow for multiple selections.


```tsx
import {
  Accordion,
  AccordionItemGroup,
  For,
  Show,
} from '@cerberus-design/react'





export function BasicDemo() {
  return (
    <Box w="2/3">
      <Accordion defaultValue={['one']}>
        <For each={data}>
          {(item) => (
            <AccordionItemGroup
              heading={item.heading}
              key={item.id}
              value={item.value}
            >
              <Show when={item.content !== null} fallback={<FallbackContent />}>
                {item.content}
              </Show>
            </AccordionItemGroup>
          )}
        </For>
      </Accordion>
    </Box>
  )
}

function FallbackContent() {
  return (
    <Box position="relative" w="full">
      <Suspense>
        <Image
          alt="A fiery cerberus"
          src="https://images-wixmp-ed30a86b8c4ca887773594c2.wixmp.com/f/4d7b49a9-2590-4dda-88ad-8046da56428b/dg97zza-65055527-eaf3-48e6-86aa-cf70a0880eea.png?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1cm46YXBwOjdlMGQxODg5ODIyNjQzNzNhNWYwZDQxNWVhMGQyNmUwIiwiaXNzIjoidXJuOmFwcDo3ZTBkMTg4OTgyMjY0MzczYTVmMGQ0MTVlYTBkMjZlMCIsIm9iaiI6W1t7InBhdGgiOiJcL2ZcLzRkN2I0OWE5LTI1OTAtNGRkYS04OGFkLTgwNDZkYTU2NDI4YlwvZGc5N3p6YS02NTA1NTUyNy1lYWYzLTQ4ZTYtODZhYS1jZjcwYTA4ODBlZWEucG5nIn1dXSwiYXVkIjpbInVybjpzZXJ2aWNlOmZpbGUuZG93bmxvYWQiXX0.BT7UC12eP5ibJs6uEYPIOQNQ6Xdnvw1ttIrCEgPvcSk"
          height={447}
          width={794}
        />
      </Suspense>
    </Box>
  )
}
```


## Indicator Position

The `AccordionItemGroup` component supports two indicator positions: `start` and `end`. This changes the position of the icon indicator displayed.


```tsx
import {
  Accordion,
  AccordionItemGroup,
  For,
  Show,
} from '@cerberus-design/react'



export function IndicatorDemo() {
  return (
    <Box w="2/3">
      <Accordion defaultValue={['one']}>
        <For each={data}>
          {(item) => (
            <AccordionItemGroup
              indicatorPosition="start"
              heading={item.heading}
              key={item.id}
              value={item.value}
            >
              <Show when={item.content !== null}>{item.content}</Show>
            </AccordionItemGroup>
          )}
        </For>
      </Accordion>
    </Box>
  )
}
```


## Sizes

The `Accordion` component supports two sizes: `sm` and `lg`. This changes the size of the icon indicator displayed.


```tsx
import {
  Accordion,
  AccordionItemGroup,
  For,
  Show,
} from '@cerberus-design/react'



export function SizeDemo() {
  return (
    <Box w="2/3">
      <Accordion defaultValue={['one']} size="sm">
        <For each={data}>
          {(item) => (
            <AccordionItemGroup
              heading={item.heading}
              key={item.id}
              value={item.value}
            >
              <Show when={item.content !== null}>{item.content}</Show>
            </AccordionItemGroup>
          )}
        </For>
      </Accordion>
    </Box>
  )
}
```


## Customizing

You can customize the Accordion using style props and data selectors.


```tsx



export function CustomDemo() {
  return (
    <Box w="2/3">
      <AccordionParts.Root transform="skewX(-10deg)">
        <AccordionParts.Item bgColor="black" borderColor="red" value="one">
          <AccordionParts.ItemTrigger data-indicator-position="start" color="red">
            <AccordionParts.ItemIndicator>🔥</AccordionParts.ItemIndicator>
            Cerberus
          </AccordionParts.ItemTrigger>

          <AccordionParts.ItemContent
            color="white"
            paddingInline="md"
            textStyle="body-md"
          >
            Cerberus is the three-headed dog that guards the gates of the Underworld and
            our sweet baby boi protecting the integrity of your design system.
          </AccordionParts.ItemContent>
        </AccordionParts.Item>
      </AccordionParts.Root>
    </Box>
  )
}
```


## Primitives

The layers of the Accordion which can be used to create a fully custom solution.

| Component              | Description                                                        |
| ---------------------- | ------------------------------------------------------------------ |
| AccordionRoot          | The main container for the accordion items.                        |
| AccordionItem          | Represents a single item within the accordion.                     |
| AccordionItemTrigger   | The trigger element that toggles the visibility of the content.    |
| AccordionItemContent   | The content that is shown or hidden when the trigger is activated. |
| AccordionItemIndicator | An optional indicator to show the state of the accordion item.     |

### Data Attributes

The primitives additionally use the following data attributes for custom styling:

| Name         | Value            | Description                            |
| ------------ | ---------------- | -------------------------------------- |
| `data-scope` | `accordion`      | The scope of the components.           |
| `data-part`  | `root`           | The root layer of the scope.           |
| `data-part`  | `item`           | The item layer of the scope.           |
| `data-part`  | `item-trigger`   | The item trigger layer of the scope.   |
| `data-part`  | `item-content`   | The item content layer of the scope.   |
| `data-part`  | `item-indicator` | The item indicator layer of the scope. |

## API

### Accordion

The `Accordion` component is an abstraction of the primitives and accepts the following props:

| Name | Default | Description                     |
| ---- | ------- | ------------------------------- |
| size | `lg`    | The size of the accordion item. |

The Accordion is an abstraction of the [Root component](https://ark-ui.com/react/docs/components/accordion#api-reference).

### AccordionItemGroup

The `AccordionItemGroup` component is an abstraction of the primitives and accepts the following props:

| Name              | Default | Description                                      |
| ----------------- | ------- | ------------------------------------------------ |
| heading           |         | The heading of the accordion item.               |
| value             |         | The value of the accordion item. Must be unique. |
| indicatorPosition | `end`   | The position of the indicator.                   |

The AccordionItemGroup is an abstraction of the [Item component](https://ark-ui.com/react/docs/components/accordion#api-reference).

### Parts

The `AccordionParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the AccordionParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name          | Description                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------ |
| Root          | The `AccordionRoot` component which is the Provider for the family.                                    |
| Item          | The `AccordionItem` component which displays the item.                                                 |
| ItemTrigger   | The `AccordionItemTrigger` component which is the visual title that triggers the content to open.      |
| ItemContent   | The `AccordionItemContent` component which displays the content that is revealed from the ItemTrigger. |
| ItemIndicator | The `AccordionItemIndicator` component which displays the indicator (chevron) icon.                    |


---
## admonition

---
title: 'Admonition'
description: 'An abstracted informational component that can be used to display important messages or warnings to users.'
npm: '@cerberus-design/react'
source: 'components/admonition'
recipe: 'slots/admonition.ts'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The `Admonition` component is used to display static messagesto users.
It can be used in various contexts, such as error, success, or informational messages.


```tsx



export function BasicDemo() {
  return (
    <Box w="3/4">
      <Admonition heading="Note">
        This is a note admonition that is commonly use to display a page-level informational
        message.
      </Admonition>
    </Box>
  )
}
```


## Palette

The `Admonition` component can be customized with different color palettes to
match the design of your application. You can use any of the state-related palettes
along with `page`.


```tsx



export function PaletteDemo() {
  const palettes: AdmonitionProps['palette'][] = ['page', 'info', 'success', 'warning', 'danger']

  return (
    <Stack w="3/4">
      <For each={palettes}>
        {(palette) => (
          <Admonition key={palette} heading="Heading" palette={palette}>
            This is a {palette} admonition.
          </Admonition>
        )}
      </For>
    </Stack>
  )
}
```


## Usage

Use the `usage` prop to display the admonition in a different style. The options
are `filled` (default) and `outlined`.


```tsx



export function UsageDemo() {
  const palettes: AdmonitionProps['palette'][] = ['page', 'info', 'success', 'warning', 'danger']

  return (
    <Stack w="3/4">
      <For each={palettes}>
        {(palette) => (
          <Admonition key={palette} heading="Heading" palette={palette} usage="outlined">
            This is a {palette} admonition.
          </Admonition>
        )}
      </For>
    </Stack>
  )
}
```


## Customizing

You can customize the Admonition any way you like with style props and data-selectors.


```tsx




export function CustomDemo() {
  return (
    <Box w="3/4">
      <AdmonitionParts.Root
        css={{
          transform: 'skewX(-10deg)',
        }}
      >
        <AdmonitionParts.Indicator>
          <Circle size="6">
            <PawIcon />
          </Circle>
        </AdmonitionParts.Indicator>

        <AdmonitionParts.Content>
          <AdmonitionParts.Heading
            css={{
              color: 'danger.text.initial',
              textTransform: 'uppercase',
            }}
          >
            Cerberus Forever
          </AdmonitionParts.Heading>
          <AdmonitionParts.Description>
            President&apos;s are temporary, but Cerberus is forever.
          </AdmonitionParts.Description>
        </AdmonitionParts.Content>
      </AdmonitionParts.Root>
    </Box>
  )
}
```


## Primitives

You can utilize the primitive components or style props to customize the
admonition.

| Component             | Description                             |
| --------------------- | --------------------------------------- |
| AdmonitionRoot        | The container for the parts             |
| AdmonitionIndicator   | The icon of the admonition              |
| AdmonitionContent     | The content container of the admonition |
| AdmonitionHeading     | The heading of the admonition           |
| AdmonitionDescription | The description body of the admonition  |

### Data Attributes

The primitives additionally use the following data attributes for custom styling:

| Name         | Value         | Description                  |
| ------------ | ------------- | ---------------------------- |
| `data-scope` | `admonition`  | The scope of the components. |
| `data-part`  | `root`        | The part of the component.   |
| `data-part`  | `indicator`   | The part of the component.   |
| `data-part`  | `content`     | The part of the component.   |
| `data-part`  | `heading`     | The part of the component.   |
| `data-part`  | `description` | The part of the component.   |

## API

### Props

The `Admonition` component is an abstraction of the primitives and accepts the following props:

| Name    | Default  | Description                                                 |
| ------- | -------- | ----------------------------------------------------------- |
| heading |          | The heading title of the Admonition.                        |
| icon    |          | An alternative icon to display in the Admonition.           |
| palette | `page`   | The color palette of the Admonition.                        |
| usage   | `filled` | The usage of the Admonition. Can be `filled` or `outlined`. |

### Parts

The `AdmonitionParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the AdmonitionParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name        | Description                                                                 |
| ----------- | --------------------------------------------------------------------------- |
| Root        | The `AdmonitionRoot` component which is the container of the family.        |
| Indicator   | The `AdmonitionIndicator` component which is the icon of the admonition.    |
| Content     | The `AdmonitionContent` component which is the container of the admonition. |
| Heading     | The `AdmonitionHeading` component which is the heading of the admonition.   |
| Description | The `Admonition` component which is the description body of the admonition. |


---
## aspect-ratio

---
title: Aspect Ratio
description: Used to embed responsive videos and maps, etc.
panda: https://panda-css.com/docs/concepts/patterns#aspect-ratio
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage


```tsx


export function BasicDemo() {
  return (
    <AspectRatio h="315px" w="560px">
      <iframe
        width="560"
        height="315"
        src="https://www.youtube.com/embed/3De7DAcouMg?si=GimPs_G6HF59kxes"
        title="YouTube video player"
        allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share"
        referrerPolicy="strict-origin-when-cross-origin"
        allowFullScreen
      />
    </AspectRatio>
  )
}
```


### Image

Here's how to embed an image that has a 4 by 3 aspect ratio.


```tsx



export function ImgDemo() {
  return (
    <AspectRatio h="447px" maxW="400px" ratio={4 / 3} w="794px">
      <Image
        alt="A fiery cerberus"
        src="https://images-wixmp-ed30a86b8c4ca887773594c2.wixmp.com/f/4d7b49a9-2590-4dda-88ad-8046da56428b/dg97zza-65055527-eaf3-48e6-86aa-cf70a0880eea.png?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1cm46YXBwOjdlMGQxODg5ODIyNjQzNzNhNWYwZDQxNWVhMGQyNmUwIiwiaXNzIjoidXJuOmFwcDo3ZTBkMTg4OTgyMjY0MzczYTVmMGQ0MTVlYTBkMjZlMCIsIm9iaiI6W1t7InBhdGgiOiJcL2ZcLzRkN2I0OWE5LTI1OTAtNGRkYS04OGFkLTgwNDZkYTU2NDI4YlwvZGc5N3p6YS02NTA1NTUyNy1lYWYzLTQ4ZTYtODZhYS1jZjcwYTA4ODBlZWEucG5nIn1dXSwiYXVkIjpbInVybjpzZXJ2aWNlOmZpbGUuZG93bmxvYWQiXX0.BT7UC12eP5ibJs6uEYPIOQNQ6Xdnvw1ttIrCEgPvcSk"
        height={447}
        width={794}
      />
    </AspectRatio>
  )
}
```


### Video

To embed a video with a specific aspect ratio, use an iframe with `src` pointing
to the link of the video.


```tsx
Example not found
```


### Google Map

Here's how to embed a responsive Google map using `AspectRatio`.


```tsx


export function MapsDemo() {
  return (
    <AspectRatio ratio={16 / 9} w="full">
      <iframe src="https://www.google.com/maps/embed?pb=!1m18!1m12!1m3!1d3963.952912260219!2d3.375295414770757!3d6.5276316452784755!2m3!1f0!2f0!3f0!3m2!1i1024!2i768!4f13.1!3m3!1m2!1s0x103b8b2ae68280c1%3A0xdc9e87a367c3d9cb!2sLagos!5e0!3m2!1sen!2sng!4v1567723392506!5m2!1sen!2sng" />
    </AspectRatio>
  )
}
```


### Responsive

Here's an example of applying a responsive aspect ratio to a box.


```tsx



export function ResponsiveDemo() {
  return (
    <AspectRatio maxWidth="300px" ratio={{ base: 1, md: 16 / 9 }} w="full">
      <DecorativeBox>Box</DecorativeBox>
    </AspectRatio>
  )
}
```


## Props

These props can be passed to the `AspectRatio` component.

| Prop        | Type         | Description                                    |
|-------------|--------------|------------------------------------------------|
| `ratio`     | `ConditionalValue<number>`     | The aspect ratio of the Box. Common values are: `21/9`, `16/9`, `9/16`, `4/3`, `1.85/1`      |


---
## avatar

---
title: Avatar
description: The Avatar component is used to represent user profile picture or initials.
npm: '@cerberus-design/react'
source: 'components/avatar'
recipe: '/slots/avatar.ts'
ark: 'avatar'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The `Avatar` component is used to represent a user or entity. It can be used to display a user's profile picture, initials, or a generic icon.

> **Note:** The avatar uses a smart hierarchy method. If a source is provided and loads successfully - it will be shown. In all other cases, the fallback will be shown.


```tsx




export function BasicDemo() {
  return (
    <HStack justify="center" w="3/4">
      <Avatar bgColor="page.bg.200" fallback={<UserAvatar />} />
      <Avatar bgColor="page.bg.200" fallback="md" />
      <Avatar
        alt="User Avatar"
        fallback="md"
        src="https://avatars.githubusercontent.com/u/71111994?s=200&v=4"
      />
    </HStack>
  )
}
```


## Sizes

You can change the size of an Avatar with the `size` prop.


```tsx



export function SizesDemo() {
  return (
    <HStack justify="center" w="3/4">
      <Avatar bgColor="page.bg.200" fallback="xs" size="xs" />
      <Avatar bgColor="page.bg.200" fallback="sm" size="sm" />
      <Avatar bgColor="page.bg.200" fallback="md" size="md" />
      <Avatar bgColor="page.bg.200" fallback="lg" size="lg" />
      <Avatar bgColor="page.bg.200" fallback="xl" size="xl" />
      <Avatar bgColor="page.bg.200" fallback="2x" size="2xl" />
      <Avatar bgColor="page.bg.200" fallback="3x" size="3xl" />
      <Avatar bgColor="page.bg.200" fallback="4x" size="4xl" />
    </HStack>
  )
}
```


## Gradients

Use the `gradient` prop to use any [gradient](/docs/theming/gradients) for the background color.


```tsx





export function GradientDemo() {
  return (
    <Grid
      columns={{
        base: 1,
        md: 2,
      }}
      columnGap="xl"
      rowGap="md"
    >
      <For each={GRADIENTS}>
        {(gradient) => (
          <GridItem colSpan={1} key={gradient}>
            <HStack gap="md">
              <Avatar fallback={<UserAvatar />} gradient={gradient} />
              <Text textStyle="label-sm">{gradient}</Text>
            </HStack>
          </GridItem>
        )}
      </For>
    </Grid>
  )
}
```


## Group

Use the `Group` component to stack Avatars together.


```tsx



export function GroupDemo() {
  return (
    <Group layout="stack" orientation="horizontal">
      <Avatar bgColor="page.bg.200" fallback={<UserAvatar />} />
      <Avatar bgColor="page.bg.100" fallback="md" />
      <Avatar
        alt="User Avatar"
        fallback="md"
        src="https://avatars.githubusercontent.com/u/71111994?s=200&v=4"
      />
    </Group>
  )
}
```


## Badge

Use the `Float` component to show badges.


```tsx




export function FloatDemo() {
  return (
    <HStack justify="center" w="3/4">
      <Box pos="relative">
        <Avatar bgColor="page.bg.200" fallback={<UserAvatar />} />
        <Float placement="bottom-end" offsetX="1" offsetY="1">
          <Circle
            bgColor="success.bg.active"
            outline="0.2em solid"
            outlineColor="page.surface.initial"
            size="8px"
          />
        </Float>
      </Box>
    </HStack>
  )
}
```


## `asChild` Prop

You can use the `asChild` prop to render the `Avatar` component as a different element. Cerberus will pass all the props onto your child.

This is great for when you need to link the avatar to a profile page.


```tsx





export function NextDemo() {
  return (
    <AvatarRoot size="lg" asChild>
      <Link href="/">
        <Image
          alt="Protector Cerberus"
          className={css({
            objectFit: 'cover',
          })}
          src="https://cerberus.digitalu.design/logo.svg"
          height={50}
          width={50}
        />
      </Link>
    </AvatarRoot>
  )
}
```


## Customization

You can customize the Avatar any way you like with style props and data-selectors.


```tsx


export function CustomAvatar() {
  return (
    <Avatar
      fallback="Cu"
      bgColor="black"
      bgImage="none"
      border="2px solid"
      borderColor="danger.border.initial"
      color="danger.text.initial"
      fontFamily="sans"
      rounded="sm"
      transform="skewX(-10deg)"
    />
  )
}
```


## Primitives

The layers of the Avatar which can be used to create a fully custom solution.

| Component      | Description                                    |
| -------------- | ---------------------------------------------- |
| AvatarRoot     | The context provider for the Avatar parts      |
| AvatarImage    | The img of the avatar                          |
| AvatarFallback | The fallback content to display for the avatar |

### Data Attributes

The primitives additionally use the following data attributes for custom styling:

| Name         | Value      | Description                      |
| ------------ | ---------- | -------------------------------- |
| `data-scope` | `avatar`   | The scope of the components.     |
| `data-part`  | `root`     | The root layer of the scope.     |
| `data-part`  | `fallback` | The fallback layer of the scope. |
| `data-part`  | `image`    | The image layer of the scope.    |

## API

### Props

The `Avatar` component is an abstraction of the primitives and accepts the following props:

| Name     | Default | Description                                       |
| -------- | ------- | ------------------------------------------------- |
| fallback |         | The fallback content to display for the avatar.   |
| src      |         | The `src` of the avatar.                          |
| alt      |         | The `alt` of the avatar. Required if using `src`. |
| gradient | `none`  | The gradient theme to display                     |
| size     | `md`    | This size of the avatar.                          |

The `Avatar` component also accepts all the props of the [`AvatarRoot` primitive props](https://ark-ui.com/react/docs/components/avatar#api-reference)

### Parts

The `AvatarParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the AvatarParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name     | Description                                                                                               |
| -------- | --------------------------------------------------------------------------------------------------------- |
| Root     | The `AvatarRoot` component which is the Provider for the family.                                          |
| Image    | The `AvatarImage` component which displays the image.                                                     |
| Fallback | The `AvatarFallback` component which is the content to show when there is no image (or it fails to load). |


---
## bleed

---
title: Bleed
description: Used to break an element from the boundaries of its container
panda: https://panda-css.com/docs/concepts/patterns#bleed
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The Bleed pattern is used to create a full width element by negating the padding 
applied to its parent container.


```tsx




export function BasicDemo() {
  return (
    <Box padding="10" rounded="sm" borderWidth="1px">
      <Bleed inline="10">
        <DecorativeBox height="20">Bleed</DecorativeBox>
      </Bleed>

      <VStack mt="6">
        <Text as="h1" size="md">
          Some Heading
        </Text>
        <Text>This is some descriptive content of the heading.</Text>
      </VStack>
    </Box>
  )
}
```


### Vertical

Use the `block` prop to make the element bleed vertically.


```tsx



export function VerticalDemo() {
  return (
    <Box padding="10" rounded="sm" borderWidth="1px">
      <Bleed block="10">
        <DecorativeBox height="20">Bleed</DecorativeBox>
      </Bleed>
    </Box>
  )
}
```


### Specific Direction

Use the `inline` and `block` props to make the element bleed in a specific direction.


```tsx



export function DirectionDemo() {
  return (
    <VStack gap="8">
      <Box padding="8" rounded="sm" borderWidth="1px">
        <Bleed inline="8">
          <DecorativeBox height="8">inline</DecorativeBox>
        </Bleed>
      </Box>

      <Box padding="8" rounded="sm" borderWidth="1px">
        <Bleed block="8">
          <DecorativeBox height="8">block</DecorativeBox>
        </Bleed>
      </Box>
    </VStack>
  )
}
```


## Props

| Prop         | Type        | Description                                     |
|--------------|-------------|-------------------------------------------------|
| `inline`     | `SystemStyleObject['marginInline']`     | The negative margin on the x-axis. |
| `block`      | `SystemStyleObject['marginBlock']`    | The negative margin on the y-axis.  |


---
## box

---
title: Box
description:
  The most abstract styling component in Cerberus on top of which all other
  Cerberus components are built.
panda: https://panda-css.com/docs/concepts/patterns#box
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The Box pattern does not contain any additional styles. With its function form 
it's the equivalent of the css function. It can be useful with its JSX form and 
is the equivalent of a styled.div component, serving mostly to get style props 
available in JSX.


```tsx


export function BasicDemo() {
  return (
    <Box bgColor="page.bg.100" color="white" padding="4" width="3/4">
      This is the Box
    </Box>
  )
}
```


### Shorthand

Use shorthand like `bgColor` instead of `backgroundColor`, `m` instead of `margin`, etc.


```tsx


export function ShorthandDemo() {
  return (
    <Box bgColor="page.bg.100" color="page.text.100" m="md" p="md" w="full">
      This is the Box
    </Box>
  )
}
```


### Pseudo Props

Use pseudo props like `_hover` to apply styles on hover, `_focus` to apply
styles on focus, etc.


```tsx


export function PsuedoDemo() {
  return (
    <Box bg="tomato" w="100%" p="4" color="white" _hover={{ bg: 'green' }}>
      A Box is not a Button
    </Box>
  )
}
```


### Border

Use the `border` and `borderColor` prop to apply border styles.


```tsx


export function BorderDemo() {
  return (
    <Box
      border="1px solid"
      borderColor="page.border.initial"
      color="page.text.100"
      p="4"
    >
      Box with a border
    </Box>
  )
}
```


### Shadow

Use the `boxShadow` or `shadow` prop to apply shadow styles.


```tsx


export function ShadowDemo() {
  return (
    <Box
      bgColor="page.surface.100"
      color="page.text.100"
      p="4"
      rounded="md"
      shadow="md"
    >
      This is the Box with shadow
    </Box>
  )
}
```


## Props

The `Box` component supports all CSS properties as props, making it easy to
style elements.


---
## button

---
title: Button
description: Used to trigger actions or events.
npm: '@cerberus-design/react'
source: 'components/button'
recipe: 'button.ts'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage


```tsx


export function BasicDemo() {
  return <Button>Default</Button>
}
```


### With Icon

To display an icon, use the `ButtonParts` API.


```tsx
'use client'




export function IconDemo() {
  return (
    <Button>
      With icon
      <Button.Icon>
        <ArrowDownRight />
      </Button.Icon>
    </Button>
  )
}
```


> **Note:** When using the pending prop, the icon will be replaced with a spinner.

## Pending

To display a loading state, use the `ButtonParts.Icon` and set the `pending` prop to `true`.


```tsx
'use client'



export function PendingDemo() {
  return (
    <Button pending>
      <Button.Icon />
      Pending
    </Button>
  )
}
```


## Shapes

Use the `shape` prop to set the shape of the button. The `Button` component comes in three shapes: `default`, `sharp` and `rounded`.


```tsx



export function ShapesDemo() {
  return (
    <HStack>
      <Button shape="default">Default</Button>
      <Button shape="sharp">Sharp</Button>
      <Button shape="rounded">Rounded</Button>
    </HStack>
  )
}
```


## Usage

Use the `usage` prop to set the usage style of the button. The `Button` component comes in three usage styles: `filled`, `outlined`, and `ghost`.


```tsx



export function UsageDemo() {
  return (
    <HStack>
      <Button usage="filled">Filled</Button>
      <Button usage="outlined">Outlined</Button>
      <Button usage="outlined-subtle">Outlined Subtle</Button>
      <Button usage="ghost">Ghost</Button>
    </HStack>
  )
}
```


## Sizes

Use the `size` prop to change the Button size. The options are `xs` up to `2xl`.


```tsx




const sizes = (recipesSpec.data.find((r) => r.name === 'button')?.variants.size ??
  []) as ButtonProps['size'][]

export function SizeDemo() {
  return (
    <HStack>
      <For each={sizes}>
        {(size) => (
          <Button key={size} size={size}>
            {size}
          </Button>
        )}
      </For>
    </HStack>
  )
}
```


## Group

You can group buttons together using the `ButtonGroup` component.


```tsx


export function GroupDemo() {
  return (
    <ButtonGroup>
      <Button>Button 1</Button>
      <Button>Button 2</Button>
      <Button>Button 3</Button>
    </ButtonGroup>
  )
}
```


### Attached Button Group

You can create an attached button group by setting the `layout` prop to `attached`.


```tsx




export function AttachedDemo() {
  return (
    <HStack justify="center" w="full">
      <ButtonGroup layout="attached">
        <Button>Main action</Button>
        <IconButton ariaLabel="View options" shape="square" usage="filled">
          <ChevronDown />
        </IconButton>
      </ButtonGroup>

      <ButtonGroup layout="attached">
        <Button usage="outlined">Main action</Button>
        <IconButton ariaLabel="View options" shape="square" usage="outlined">
          <ChevronDown />
        </IconButton>
      </ButtonGroup>
    </HStack>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the button.

| Component   | Description                               |
| ----------- | ----------------------------------------- |
| Button.Root | The context provider for the Button parts |
| Button.Icon | The icon/spinner of the button            |


```tsx


export function CustomDemo() {
  return (
    <Button
      bgColor="danger.bg.initial"
      color="danger.text.initial"
      rounded="md"
      transform="skew(-10deg)"
      _hover={{
        bgColor: 'black',
        color: 'yellow',
      }}
    >
      Cerberus Forever
    </Button>
  )
}
```


## Global Customization

To enable global customization, you can modify the `theme` configuration in your `panda.config.ts` file. For example, to customize the button component globally:


```tsx


export default createCerberusConfig({
  // ...
  theme: {
    extend: {
      recipes: {
        button: {
          defaultVariants: {
            shape: 'default',
          },
        },
      },
    },
  },
})
```

<br />

This change will set the default shape variant of all buttons to `default`.

## API

### Props

The `Button` component is an abstraction of the primitives and accepts the following props:

| Name      | Default  | Description                                                                                                                          |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `palette` | `action` | The color palette (any of the Cerberus palettes) of the button.                                                                      |
| `usage`   | `filled` | The style treatment of the button.                                                                                                   |
| `shape`   | `sharp`  | The shape of the button.                                                                                                             |
| `size`    | `lg`     | The size of the Button.                                                                                                              |
| `pending` | `false`  | The loading state of the button. When a button has an `Icon` it will replace it with a spinner. When not, is shows a disabled state. |
| `asChild` |          | Render the Button as the child component.                                                                                            |

#### ButtonGroup Props

| Name   | Default   | Description                                                                                           |
| ------ | --------- | ----------------------------------------------------------------------------------------------------- |
| layout | `default` | The layout of the button group. Can be `default` or `attached`.                                       |
| shape  | `sharp`   | The shape of the buttons in the group. Should match the `shape` prop of the `Button` components used. |


---
## carousel

---
title: Carousel
description: Used to cycle through a series of visual content within a container.
npm: '@cerberus-design/react'
source: 'components/carousel'
recipe: 'slots/carousel.ts'
ark: 'carousel'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage


```tsx




export function BasicDemo() {
  return (
    <Carousel.Root
      defaultPage={0}
      padding="1rem"
      slideCount={ITEMS.length}
      slidesPerPage={2.5}
      spacing="1rem"
    >
      <Carousel.ItemGroup>
        <For each={ITEMS}>
          {(item, idx) => (
            <Carousel.Item key={item.id} index={idx} asChild>
              <Center
                bgColor="page.bg.100"
                border="1px solid"
                borderColor="page.border.200"
                color="page.text.100"
                h="21rem"
                rounded="md"
                transitionProperty="all"
                transitionDuration="normal"
                transitionTimingFunction="cubic-bezier(0.075, 0.82, 0.165, 1)"
                willChange="z-index, transform, box-shadow"
                _hover={{
                  shadow: 'lg',
                  transform: 'scale(1.2)',
                  zIndex: 'decorator',
                }}
              >
                {item.content}
              </Center>
            </Carousel.Item>
          )}
        </For>
      </Carousel.ItemGroup>

      <Carousel.Control>
        <Carousel.PrevTrigger asChild>
          <Button shape="rounded" size="sm" usage="outlined">
            Prev
          </Button>
        </Carousel.PrevTrigger>
        <Carousel.NextTrigger asChild>
          <Button shape="rounded" size="sm" usage="outlined">
            Next
          </Button>
        </Carousel.NextTrigger>
      </Carousel.Control>
    </Carousel.Root>
  )
}
```


## With Indicators

Use the `showIndicators` prop to display indicators for each slide.


```tsx




export function IndicatorDemo() {
  return (
    <Carousel.Root
      defaultPage={0}
      padding="1rem"
      slideCount={ITEMS.length}
      slidesPerPage={1}
      spacing="1rem"
      showIndicators
    >
      <Carousel.ItemGroup>
        <For each={ITEMS}>
          {(item, idx) => (
            <Carousel.Item key={item.id} index={idx} asChild>
              <Center
                bgColor="page.bg.100"
                border="1px solid"
                borderColor="page.border.200"
                color="page.text.100"
                h="16rem"
                rounded="md"
                transitionProperty="all"
                transitionDuration="normal"
                transitionTimingFunction="cubic-bezier(0.075, 0.82, 0.165, 1)"
                willChange="z-index, transform, box-shadow"
              >
                {item.content}
              </Center>
            </Carousel.Item>
          )}
        </For>
      </Carousel.ItemGroup>
    </Carousel.Root>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the button.

| Component              | Description                                      |
| ---------------------- | ------------------------------------------------ |
| CarouselRoot           | The context provider for the Carousel parts      |
| CarouselControl        | The container of the Next and Prev triggers      |
| CarouselPrevTrigger    | The button to navigate to the previous slide     |
| CarouselNextTrigger    | The button to navigate to the next slide         |
| CarouselItemGroup      | The container for the Carousel items             |
| CarouselItem           | The individual item within the Carousel          |
| CarouselIndicatorGroup | The container for the indicators                 |
| CarouselIndicator      | The individual indicator representing each slide |

### Data Attributes

The primitives additionally use the following data attributes for custom styling:

| Attribute            | Value                           |
| -------------------- | ------------------------------- |
| `[data-scope]`       | carousel                        |
| `[data-part]`        | root                            |
| `[data-orientation]` | The orientation of the carousel |

### Root CSS Variables

The Root primitive sets the following CSS variables for customization:

| Variable            | Description                            |
| ------------------- | -------------------------------------- |
| `--slides-per-page` | The number of slides visible per page  |
| `--slide-spacing`   | The spacing between slides             |
| `--slide-item-size` | The calculated size of each slide item |

## API

### Props

The `Carousel` component is an abstraction of the primitives and accepts the following props:

| Name           | Default | Description                                |
| -------------- | ------- | ------------------------------------------ |
| showIndicators | `false` | Whether to show indicators for each slide. |

The Carousel also accepts all the props of the [Root component](https://ark-ui.com/docs/components/carousel#api-reference).

### Parts

The `CarouselParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the CarouselParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name           | Description                                                                           |
| -------------- | ------------------------------------------------------------------------------------- |
| Root           | The `Carousel` component which is the Provider for the family.                        |
| Control        | The container of the Next and Prev triggers.                                          |
| PrevTrigger    | The button to navigate to the previous slide.                                         |
| NextTrigger    | The button to navigate to the next slide.                                             |
| ItemGroup      | The container for the Carousel items.                                                 |
| Item           | The `CarouselItem` component which represents an individual item within the carousel. |
| IndicatorGroup | The container for the indicators.                                                     |
| Indicator      | The individual indicator representing each slide.                                     |


---
## center

---
title: Center
description: Used to center its child within itself.
panda: https://panda-css.com/docs/concepts/patterns#center
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The Center pattern is used to center the content of a container.


```tsx



export function BasicDemo() {
  return (
    <Center h="100px" maxW="320px">
      <DecorativeBox p="sm">This is centered</DecorativeBox>
    </Center>
  )
}
```


### Icon

Center can be used to create frames around icons or numbers.


```tsx




export function IconDemo() {
  return (
    <HStack>
      <Center w="40px" h="40px" bg="tomato" color="white">
        <Phone />
      </Center>

      <Center w="40px" h="40px" bg="tomato" color="white">
        <Text as="span" fontWeight="bold" fontSize="lg">
          1
        </Text>
      </Center>
    </HStack>
  )
}
```


### Center with Inline

Use the `inline` to change the display to `inline-flex`.


```tsx




export function InlineDemo() {
  return (
    <Center inline bg="page.bg.100" gap="sm" h="100px" maxW="320px" px="md">
      <Phone />
      <Text>This will be centered</Text>
    </Center>
  )
}
```


### Square

`Square` centers its child given the `size` (width and height).


```tsx



export function SquareDemo() {
  return (
    <Square size="10" bg="purple.700" color="white">
      <PhoneIncoming />
    </Square>
  )
}
```


### Circle

`Circle` centers its child given the `size` and creates a circle around it.


```tsx



export function CircleDemo() {
  return (
    <Circle size="10" bgColor="danger.bg.initial" color="danger.text.100">
      <PhoneBlock />
    </Circle>
  )
}
```


## Props

Center accepts CSS properties and the following specific props:

| Prop      | Type     | Description                                      |
|-----------|----------|--------------------------------------------------|
| `inline`  | `boolean`| Changes the display to `inline-flex`.            |
| `size`    | `string` | Sets the width and height of the element.        |


---
## cerberus-context

---
title: Cerberus Context
description: Register custom options for interal component usage.
npm: '@cerberus-design/react'
source: 'components/context'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The Cerberus Context provides the ability to register custom options for internal
component usage.


```tsx
Example not found
```


## Config

The Cerberus Context configuration is passed to the `config` property of the `CerberusProvider`
via the `makeSystemConfig` helper.


```tsx
Example not found
```


## Registering Custom Icons

To register a different set of icons for your application, you can use the
`defineIcons` function and pass it to the `icons` prop of the `CerberusProvider`
`config` property.


```tsx
Example not found
```


### Icon overrides

Here is the exhaustive list of icon overrides you can configure:

| Name                  | Description                                                                       |
| --------------------- | --------------------------------------------------------------------------------- |
| `accordionIndicator`  | The arrow indicator used in accordion components.                                 |
| `arrowRight`          | The arrow indicator used for representing moving forward.                         |
| `avatar`              | The fallback icon used when no avatar is available.                               |
| `calendar`            | The calendar icon used in date picker components.                                 |
| `calendarPrev`        | The prev month trigger icon used in date picker components.                       |
| `calendarNext`        | The next month trigger icon used in date picker components.                       |
| `caretDown`           | The caret down icon used in dropdown components.                                  |
| `checkbox`            | The checkbox icon used in checkbox components.                                    |
| `close`               | The close icon used in closeable components.                                      |
| `column`              | The column icon used in column-related components.                                |
| `confirmModal`        | The header icon used in confirm modals.                                           |
| `decrement`           | The icon used for decrement triggers.                                             |
| `delete`              | The icon used for delete triggers.                                                |
| `dangerNotification`  | The icon used for danger notifications.                                           |
| `error`               | The icon used for error notifications.                                            |
| `fileUploader`        | The icon used for file uploader components.                                       |
| `filter`              | The icons used to represent filtering things.                                     |
| `filterEdit`          | The icons used to represent editing filtered things.                              |
| `filterClear`         | The icons used to represent clearing filters.                                     |
| `indeterminate`       | The icon used for indeterminate states.                                           |
| `increment`           | The icon used for increment triggers.                                             |
| `info`                | The icon used for info triggers.                                                  |
| `infoNotification`    | The icon used for info notifications.                                             |
| `invalid`             | The icon used for invalid states.                                                 |
| `invalidAlt`          | The icon used for alternative invalid states.                                     |
| `moreVertical`        | The icon used for more options triggers.                                          |
| `pinLeft`             | The icon used for pin left triggers.                                              |
| `pinLeftFilled`       | The icon used for pin left triggers with a filled style.                          |
| `pinRight`            | The icon used for pin right triggers.                                             |
| `pinRightFilled`      | The icon used for pin right triggers with a filled style.                         |
| `promptModal`         | The icon used for prompt modal triggers.                                          |
| `redo`                | The icon used for redo triggers.                                                  |
| `search`              | The icon used for search triggers.                                                |
| `selectArrow`         | The icon used for select menu triggers.                                           |
| `selectChecked`       | The icon used for the checked state of a select menu item.                        |
| `sortAsc`             | The icon used for ascending sort triggers.                                        |
| `sortDesc`            | The icon used for descending sort triggers.                                       |
| `success`             | The icon used for success triggers.                                               |
| `successNotification` | The icon used for success notifications.                                          |
| `table`               | An icon used to represent tables.                                                 |
| `toggleChecked`       | The icon used for toggle checked triggers.                                        |
| `viewOff`             | The icon used for view off triggers (e.g., hide items, password visibility, etc.) |
| `waitingFileUploader` | The icon used for a loading state in the File Uploader.                           |
| `warningNotification` | The icon used for warning notifications.                                          |
| `warning`             | The icon used for warning triggers.                                               |

## Config Options

| Name    | Description                                       |
| ------- | ------------------------------------------------- |
| `icons` | Custom icons to register for all component usage. |


---
## checkbox

---
title: Checkbox
description: 'The Checkbox component allows users to select one or more options from a set.'
npm: '@cerberus-design/react'
source: 'components/checkbox'
recipe: 'slots/checkbox.ts'
ark: 'checkbox'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The Checkbox component is a controlled component that can be used to select one or more options from a set. It can be used in a group with other checkboxes to allow for multiple selections.


```tsx
'use client'




const items = [
  {
    id: 'terms',
    label: 'I agree to the terms and conditions',
    required: true,
  },
  {
    id: 'legal',
    label: 'I would like to receive marketing emails',
  },
]

export function BasicDemo() {
  return (
    <Box w="1/2">
      <CheckboxGroup name="user_acceptance">
        <For each={items}>
          {(item) => (
            <Checkbox
              key={item.id}
              ids={{ control: item.id }}
              required={item?.required}
            >
              {item.label}
            </Checkbox>
          )}
        </For>

        <Checkbox ids={{ control: 'mixed' }} checked="indeterminate">
          The indeterminate state
        </Checkbox>
      </CheckboxGroup>
    </Box>
  )
}
```


## Indeterminate State

The Checkbox component supports the indeterminate state, which is useful for indicating that a group of checkboxes is in a mixed state. To enable this state, set the `checked` prop to `indeterminate`.


```tsx
'use client'





const initialValues = [
  { label: 'Monday', checked: false, value: 'monday' },
  { label: 'Tuesday', checked: false, value: 'tuesday' },
  { label: 'Wednesday', checked: false, value: 'wednesday' },
  { label: 'Thursday', checked: false, value: 'thursday' },
]

export function IndeterminateDemo() {
  const [values, setValues] = useSignal(initialValues)

  const allChecked = createComputed(() => values.every((value) => value.checked))
  const indeterminate = createComputed(
    () => values.some((value) => value.checked) && !allChecked(),
  )

  return (
    <Box w="1/2">
      <CheckboxGroup name="days">
        <Checkbox
          checked={indeterminate() ? 'indeterminate' : allChecked()}
          onCheckedChange={(e) => {
            setValues((current) =>
              current.map((value) => ({ ...value, checked: !!e.checked })),
            )
          }}
        >
          Weekdays
        </Checkbox>

        <For each={values}>
          {(item, index) => (
            <Checkbox
              key={item.value}
              checked={item.checked}
              onCheckedChange={(e) => {
                setValues((current) => {
                  const newValues = [...current]
                  newValues[index] = { ...newValues[index], checked: !!e.checked }
                  return newValues
                })
              }}
            >
              {item.label}
            </Checkbox>
          )}
        </For>
      </CheckboxGroup>
    </Box>
  )
}
```


## Sizes

The Checkbox component supports different sizes. You can set the size prop to `sm`, or `md`.


```tsx
'use client'




export function SizeDemo() {
  return (
    <Box w="1/2">
      <CheckboxGroup name="size">
        <Checkbox ids={{ control: 'small' }} size="sm">
          Small
        </Checkbox>
        <Checkbox ids={{ control: 'medium' }} size="md">
          Medium
        </Checkbox>
      </CheckboxGroup>
    </Box>
  )
}
```


## Customizing

You can customize the Checkbox any way you like with style props and data-selectors.


```tsx
'use client'





export function CustomDemo() {
  return (
    <Box w="1/2">
      <CheckboxParts.Root>
        <CheckboxParts.Label>Custom Checkbox</CheckboxParts.Label>
        <CheckboxParts.Control
          bgColor="black"
          border="4px solid"
          borderColor="danger.border.initial"
          h={8}
          rounded="none"
          transform="skewX(-10deg)"
          w={8}
          _checked={{
            bgColor: 'info.bg.initial',
          }}
        >
          <CheckboxParts.Indicator>
            <ArrowDownRight />
          </CheckboxParts.Indicator>
        </CheckboxParts.Control>
        <CheckboxParts.HiddenInput />
      </CheckboxParts.Root>
    </Box>
  )
}
```


## Primitives

The layers of the Checkbox which can be used to create a fully custom solution.

| Component           | Description                                 |
| ------------------- | ------------------------------------------- |
| CheckboxRoot        | The context provider for the Checkbox parts |
| CheckboxLabel       | The label of the checkbox                   |
| CheckboxControl     | The input of the checkbox                   |
| CheckboxIndicator   | The indicator of the checkbox state         |
| CheckboxGroup       | The group container for multiple checkboxes |
| CheckboxHiddenInput | The native input for the checkbox           |

### Data Attributes

The primitives additionally use the following data attributes for custom styling:

| Name                 | Value                                          | Description                       |
| -------------------- | ---------------------------------------------- | --------------------------------- |
| `data-scope`         | `checkbox`                                     | The scope of the components.      |
| `data-part`          | `root`                                         | The root layer of the scope.      |
| `data-part`          | `label`                                        | The label layer of the scope.     |
| `data-part`          | `control`                                      | The control layer of the scope.   |
| `data-part`          | `indicator`                                    | The indicator layer of the scope. |
| `data-part`          | `group`                                        | The group layer of the scope.     |
| `data-active`        | Present when active or pressed                 |
| `data-focus`         | Present when focused                           |
| `data-focus-visible` | Present when focused with keyboard             |
| `data-readonly`      | Present when read-only                         |
| `data-hover`         | Present when hovered                           |
| `data-disabled`      | Present when disabled                          |
| `data-state`         | `"indeterminate"  \| "checked" \| "unchecked"` |
| `data-invalid`       | Present when invalid                           |
| `data-required`      | Present when required                          |

## API

### Props

The `Checkbox` component is an abstraction of the primitives and accepts the following props:

| Prop                        | Type                                                                             | Required | Description                                                                                                                    |
| --------------------------- | -------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `asChild`                   | `boolean`                                                                        | No       | Use the provided child element as the default rendered element, combining their props and behavior.                            |
| `size`                      | `sm`                                                                             | No       | This size of the Checkbox.                                                                                                     |
| `checked`                   | `CheckedState`                                                                   | No       | The controlled checked state of the checkbox                                                                                   |
| `defaultChecked`            | `CheckedState`                                                                   | No       | The initial checked state of the checkbox when rendered. Use when you don't need to control the checked state of the checkbox. |
| `disabled`                  | `boolean`                                                                        | No       | Whether the checkbox is disabled                                                                                               |
| `form`                      | `string`                                                                         | No       | The id of the form that the checkbox belongs to.                                                                               |
| `id`                        | `string`                                                                         | No       | The unique identifier of the machine.                                                                                          |
| `ids`                       | `Partial<{ root: string; hiddenInput: string; control: string; label: string }>` | No       | The ids of the elements in the checkbox. Useful for composition.                                                               |
| `invalid`                   | `boolean`                                                                        | No       | Whether the checkbox is invalid                                                                                                |
| `name`                      | `string`                                                                         | No       | The name of the input field in a checkbox.                                                                                     |
| Useful for form submission. |
| `onCheckedChange`           | `(details: CheckedChangeDetails) => void`                                        | No       | The callback invoked when the checked state changes.                                                                           |
| `readOnly`                  | `boolean`                                                                        | No       | Whether the checkbox is read-only                                                                                              |
| `required`                  | `boolean`                                                                        | No       | Whether the checkbox is required                                                                                               |
| `value`                     | `string`                                                                         | No       | The value of checkbox input. Useful for form submission.                                                                       |

### Parts

The `CheckboxParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the CheckboxParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name        | Description                                                                    |
| ----------- | ------------------------------------------------------------------------------ |
| Root        | The `CheckboxRoot` component which is the Provider for the family.             |
| Label       | The `CheckboxLabel` component which displays the label and "required" notice.  |
| Control     | The `CheckboxControl` component which is the visual field.                     |
| Indicator   | The `CheckboxIndicator` component which displays based on the `checked` state. |
| Group       | The `CheckboxGroup` component which creates a controls the spacing of a group. |
| HiddenInput | The `CheckboxHiddenInput` component which displays the native input.           |


---
## client-only

---
title: 'Client Only'
description: 'Renders children only on the client side.'
npm: '@cerberus-design/react'
arkUtility: 'client-only'
---

## Motivation

The `ClientOnly` component renders its children only on the client side. This is useful for components that need to
access the DOM or browser APIs that are not available on the server side.

## Examples

### Basic

```tsx


export const Basic = () => (
  <ClientOnly>
    <div>This content is only rendered on the client side.</div>
  </ClientOnly>
)

```

### With Fallback

```tsx


export const WithFallback = () => (
  <ClientOnly fallback={<div>Loading on the server...</div>}>
    <div>This content is only rendered on the client side.</div>
  </ClientOnly>
)

```

## API Reference

**Component API Reference**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `fallback` | `any` | No | Shows value when rendering on the server side |


---
## clipboard

---
title: Clipboard
description: Used to copy text to the clipboard.
npm: '@cerberus-design/react'
source: 'components/clipboard'
recipe: 'slots/clipboard.ts'
ark: 'clipboard'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The Clipboard component provides an accessible way to copy text to the user's clipboard with built-in visual feedback.

The Clipboard component is **unstyled by default**, allowing for full customization.


```tsx
'use client'




export function BasicDemo() {
  return (
    <Clipboard.Root value="Hello, World!">
      <Clipboard.Control asChild>
        <HStack gap="md" w="full">
          <Clipboard.Label asChild>
            <Text as="small" textStyle="label-sm">
              Hello, World!
            </Text>
          </Clipboard.Label>

          <Clipboard.Trigger asChild>
            <IconButton clipboard shape="square" size="sm" rounded="xs">
              <Clipboard.Indicator />
            </IconButton>
          </Clipboard.Trigger>
        </HStack>
      </Clipboard.Control>
    </Clipboard.Root>
  )
}
```


## Button

Use the `asChild` prop on the `Clipboard.Trigger` to create a copy button.


```tsx
'use client'



// [!code word:asChild]
export function ButtonDemo() {
  return (
    <Clipboard.Root value="Hello, World!">
      <Clipboard.Control>
        <Clipboard.Trigger asChild>
          <Button color="action.text.initial">
            <Clipboard.CopyText color="currentColor" />
            <Clipboard.Indicator />
          </Button>
        </Clipboard.Trigger>
      </Clipboard.Control>
    </Clipboard.Root>
  )
}
```


## Input

Use the `asChild` or style props prop on the `Clipboard.Input` to create a copy input.

> **Note:** A Button is valid as a trigger replacement because the Clipboard trigger will pass the aria attributes to the button.


```tsx
'use client'



export function InputDemo() {
  return (
    <Clipboard.Root maxW="300px" value="https://cerberus.digitalu.design/">
      <Clipboard.Control asChild>
        <Group layout="attached">
          <Clipboard.Input
            border="1px solid"
            borderColor="page.border.initial"
            px="md"
            rounded="sm"
            textStyle="label-sm"
            w="15rem"
          />
          <Clipboard.Trigger color="action.text.initial" asChild>
            <Button color="inherit" shape="default" size="md">
              <Clipboard.Indicator />
            </Button>
          </Clipboard.Trigger>
        </Group>
      </Clipboard.Control>
    </Clipboard.Root>
  )
}
```


## Store

Use the `useClipboard` hook to create a fully custom solution.


```tsx
'use client'



export function StoreDemo() {
  const clipboard = useClipboard({ value: 'https://chakra-ui.com' })
  return (
    <Button size="sm" onClick={clipboard.copy}>
      <Show when={clipboard.copied} fallback="Copy">
        Copied
      </Show>
    </Button>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the clipboard component.

| Component          | Description                                         |
| ------------------ | --------------------------------------------------- |
| ClipboardRoot      | The root context provider for the clipboard family. |
| ClipboardLabel     | A label element for accessibility.                  |
| ClipboardControl   | The wrapper for input and trigger elements.         |
| ClipboardInput     | The input element containing the text to copy.      |
| ClipboardTrigger   | The button that triggers the copy action.           |
| ClipboardIndicator | Shows the current state (copy/copied) with icons.   |
| CopyText           | Shows the current state (copy/copied) with text.    |

### Data Attributes

The Clipboard component exposes several data attributes for better accessibility and customization.

| Name          | Value                             | Description                  |
| ------------- | --------------------------------- | ---------------------------- |
| `data-scope`  | `clipboard`                       | The scope of the components. |
| `data-part`   | `root`                            | The root container part.     |
| `data-part`   | `label`                           | The label part.              |
| `data-part`   | `control`                         | The control part.            |
| `data-part`   | `input`                           | The input part.              |
| `data-part`   | `trigger`                         | The trigger part.            |
| `data-part`   | `indicator`                       | The indicator part.          |
| `data-copied` | Present when copied state is true |

## API

### Root

| Prop             | Type                                                      | Required | Description                                                                                                                   |
| ---------------- | --------------------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `asChild`        | `boolean`                                                 | No       | Use the provided child element as the default rendered element, combining their props and behavior.                           |
| `defaultValue`   | `string`                                                  | No       | The initial value to be copied to the clipboard when rendered. Use when you don't need to control the value of the clipboard. |
| `id`             | `string`                                                  | No       | The unique identifier of the machine.                                                                                         |
| `ids`            | `Partial<{ root: string; input: string; label: string }>` | No       | The ids of the elements in the clipboard. Useful for composition.                                                             |
| `onStatusChange` | `(details: CopyStatusDetails) => void`                    | No       | The function to be called when the value is copied to the clipboard                                                           |
| `onValueChange`  | `(details: ValueChangeDetails) => void`                   | No       | The function to be called when the value changes                                                                              |
| `timeout`        | `number`                                                  | No       | The timeout for the copy operation                                                                                            |
| `value`          | `string`                                                  | No       | The controlled value of the clipboard                                                                                         |

The Clipboard.Root is an abstraction of the [Root component](https://ark-ui.com/react/docs/components/clipboard#api-reference).

### Indicator

The indicator accepts the following props:

| Name | Default | Description                                                              |
| ---- | ------- | ------------------------------------------------------------------------ |
| size | `16`    | The size of the indicator (in pixels). Can be `16`, `20`, `24`, or `32`. |

### Parts

The `Clipboard` API is an Object containing the full family of components.

> **Note:** It is best to only use the Clipboard parts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name      | Description                                                                   |
| --------- | ----------------------------------------------------------------------------- |
| Root      | The `ClipboardRoot` component which is the Provider for the family.           |
| Label     | The `ClipboardLabel` component for accessibility.                             |
| Control   | The `ClipboardControl` component wrapper.                                     |
| Input     | The `ClipboardInput` component displaying the text.                           |
| Trigger   | The `ClipboardTrigger` component button.                                      |
| Indicator | The `CopyIndicator` component with default copy/checkmark icons.              |
| CopyText  | The `CopyText` component with default "Copy"/"Copied" text indicators.        |
| Context   | The raw context for accessing clipboard state within the component hierarchy. |


---
## collapsible

---
title: Collapsible
description: Used to expand and collapse additional content.
npm: '@cerberus-design/react'
source: 'components/collapsible'
recipe: 'slots/collapsible.ts'
ark: 'collapsible'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The Collapsible component allows you to show or hide content with a trigger. It is useful for accordions, dropdowns, and expandable sections.


```tsx
'use client'





export function BasicDemo() {
  return (
    <HStack h="full" w="3/4">
      <Collapsible.Root w="full">
        <Collapsible.Trigger asChild>
          <HStack gap="sm" userSelect="none">
            <Collapsible.Indicator
              transform="rotate(-90deg)"
              transition="transform 0.2s"
              _open={{ transform: 'rotate(0deg)' }}
            >
              <ChevronDown />
            </Collapsible.Indicator>
            Toggle
          </HStack>
        </Collapsible.Trigger>

        <Collapsible.Content>
          <Box
            border="1px solid"
            borderColor="page.border.initial"
            p="md"
            mt="sm"
            rounded="md"
            w="full"
          >
            Collapsible content goes here.
          </Box>
        </Collapsible.Content>
      </Collapsible.Root>
    </HStack>
  )
}
```


## Initial Open

Use the `defaultOpen` prop to render the collapsible in an open state by default.


```tsx
'use client'





export function OpenDemo() {
  return (
    <HStack h="full" w="3/4">
      <Collapsible.Root defaultOpen w="full">
        <Collapsible.Trigger asChild>
          <HStack gap="sm" userSelect="none">
            <Collapsible.Indicator
              transform="rotate(-90deg)"
              transition="transform 0.2s"
              _open={{ transform: 'rotate(0deg)' }}
            >
              <ChevronDown />
            </Collapsible.Indicator>
            Toggle
          </HStack>
        </Collapsible.Trigger>

        <Collapsible.Content>
          <Box
            border="1px solid"
            borderColor="page.border.initial"
            p="md"
            mt="sm"
            rounded="md"
            w="full"
          >
            Collapsible content goes here.
          </Box>
        </Collapsible.Content>
      </Collapsible.Root>
    </HStack>
  )
}
```


## Partial Height

Use the `collapsedHeight` prop to show a preview of the content when collapsed.


```tsx
'use client'




export function PartialDemo() {
  return (
    <HStack h="full" w="3/4">
      <Collapsible.Root collapsedHeight="100px" w="full">
        <Collapsible.Content effect="fade">
          <Box
            border="1px solid"
            borderColor="page.border.initial"
            p="md"
            mt="sm"
            rounded="md"
            w="full"
          >
            It is a long established fact that a reader will be distracted by the
            readable content of a page when looking at its layout. The point of using
            Lorem Ipsum is that it has a more-or-less normal distribution of letters, as
            opposed to using &apos;Content here, content here&apos;, making it look like
            readable English. Many desktop publishing packages and web page editors now
            use Lorem Ipsum as their default model text, and a search for &apos;lorem
            ipsum&apos; will uncover many web sites still in their infancy. Various
            versions have evolved over the years, sometimes by accident, sometimes on
            purpose (injected humour and the like).
          </Box>
        </Collapsible.Content>

        <Collapsible.Trigger asChild>
          <Button mt="md" usage="outlined-subtle">
            Show More
          </Button>
        </Collapsible.Trigger>
      </Collapsible.Root>
    </HStack>
  )
}
```


## Effects

To turn off the animation effect, you can set the `effect` prop to `none` on the `Collapsible.Content` component.


```tsx
'use client'




export function FadeDemo() {
  return (
    <HStack h="full" w="17rem">
      <Collapsible.Root>
        <Collapsible.Trigger>Toggle</Collapsible.Trigger>
        <Collapsible.Content effect="none">
          <Box
            border="1px solid"
            borderColor="page.border.initial"
            p="md"
            rounded="md"
            w="full"
          >
            Collapsible content goes here.
          </Box>
        </Collapsible.Content>
      </Collapsible.Root>
    </HStack>
  )
}
```


## Controlled

Use the `open` and `onOpenChange` props to control the collapsible state.


```tsx
'use client'





export function ControlledDemo() {
  const [open, setOpen] = useSignal<boolean>(false)

  return (
    <Stack gap="4" w="3/4">
      <Text textStyle="label-sm">Status: {open ? 'Open' : 'Closed'}</Text>

      <Collapsible.Root
        open={open}
        onOpenChange={(e: OpenChangeDetails) => setOpen(e.open)}
        w="full"
      >
        <Collapsible.Trigger paddingY="3">Toggle Collapsible</Collapsible.Trigger>
        <Collapsible.Content>
          <Box padding="4" borderWidth="1px">
            This collapsible is controlled by external state. You can open and close it
            using the buttons above or by clicking the trigger.
          </Box>
        </Collapsible.Content>
      </Collapsible.Root>
    </Stack>
  )
}
```


## Customization

You can customize the Collapsible component any way you like with style props and data-selectors.


```tsx
'use client'




export function CustomDemo() {
  return (
    <Collapsible.Root w="full">
      <Collapsible.Trigger
        color="danger.text.100"
        bgColor="danger.surface.initial"
        px="sm"
        w="full"
      >
        Custom Toggle
      </Collapsible.Trigger>
      <Collapsible.Content>
        <Box w="full">Custom collapsible content.</Box>
      </Collapsible.Content>
    </Collapsible.Root>
  )
}
```


## Primitives

You can utilize the primitive components to build a custom collapsible solution.

| Component            | Description                              |
| -------------------- | ---------------------------------------- |
| CollapsibleRoot      | The context provider of the collapsible. |
| CollapsibleTrigger   | The button that toggles the collapsible. |
| CollapsibleIndicator | The indicator that shows the state.      |
| CollapsibleContent   | The content of the collapsible.          |

### Data Attributes

The primitives additionally use the following data attributes for custom styling:

| Name         | Value                | Description                  |
| ------------ | -------------------- | ---------------------------- |
| `data-scope` | `collapsible`        | The scope of the components. |
| `data-part`  | `root`               | The root container part.     |
| `data-part`  | `trigger`            | The trigger part.            |
| `data-part`  | `indicator`          | The indicator part.          |
| `data-part`  | `content`            | The content part.            |
| `data-state` | `"open" \| "closed"` | The state of the content.    |

## API

### Collapsible

The `Collapsible` component is an Object containing all the primitive components.

#### Root Props

| Prop              | Type                                                          | Required | Description                                                                                                                    |
| ----------------- | ------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `asChild`         | `boolean`                                                     | No       | Use the provided child element as the default rendered element, combining their props and behavior.                            |
| `collapsedHeight` | `string \| number`                                            | No       | The height of the content when collapsed.                                                                                      |
| `collapsedWidth`  | `string \| number`                                            | No       | The width of the content when collapsed.                                                                                       |
| `defaultOpen`     | `boolean`                                                     | No       | The initial open state of the collapsible when rendered. Use when you don't need to control the open state of the collapsible. |
| `disabled`        | `boolean`                                                     | No       | Whether the collapsible is disabled.                                                                                           |
| `effect`          | `"none" \| "fadeIin" \| "expandIn"`                           | No       | The animation effect of the content when collapsed.                                                                            |
| `ids`             | `Partial<{ root: string; content: string; trigger: string }>` | No       | The ids of the elements in the collapsible. Useful for composition.                                                            |
| `lazyMount`       | `boolean`                                                     | No       | Whether to enable lazy mounting                                                                                                |
| `onExitComplete`  | `VoidFunction`                                                | No       | The callback invoked when the exit animation completes.                                                                        |
| `onOpenChange`    | `(details: OpenChangeDetails) => void`                        | No       | The callback invoked when the open state changes.                                                                              |
| `open`            | `boolean`                                                     | No       | The controlled open state of the collapsible.                                                                                  |
| `unmountOnExit`   | `boolean`                                                     | No       | Whether to unmount on exit.                                                                                                    |

You can see additional options for the [Root component](https://ark-ui.com/react/docs/components/collapsible#api-reference).

### Parts

The `CollapsibleParts` API is the same as the `Collapsible` component.


---
## combobox

---
title: Combobox
description: A filterable select component that allows users to search and select options.
npm: '@cerberus-design/react'
source: 'components/combobox'
recipe: 'slots/combobox.ts'
ark: 'combobox'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The `Combobox` is an abracted API that combines multiple primitives into a single root component. You combine this with the `useStatefulCollection` hook to create a filterable select component.


```tsx
'use client'


import {
  Combobox,
  ComboItemText,
  ComboItemWithIndicator,
  For,
  Text,
  useStatefulCollection,
} from '@cerberus-design/react'


export function BasicDemo() {
  const { collection, handleInputChange } = useStatefulCollection(items)

  return (
    <Box w="1/2">
      <Combobox
        collection={collection}
        label="Select Relative"
        onInputValueChange={handleInputChange}
        placeholder="Choose option"
      >
        <For
          each={collection.items}
          fallback={
            <VStack paddingBlock="6" w="full">
              <Text textAlign="center" textStyle="label-sm">
                No results found
              </Text>
            </VStack>
          }
        >
          {(item) => (
            <ComboItemWithIndicator key={item.value} item={item}>
              <ComboItemText>{item.label}</ComboItemText>
            </ComboItemWithIndicator>
          )}
        </For>
      </Combobox>
    </Box>
  )
}
```


## With Start Icon

To add an icon to the start position of the input, use the `startIcon` prop to pass in your icon of choice.


```tsx
'use client'



import {
  Combobox,
  ComboItemText,
  ComboItemWithIndicator,
  For,
  Text,
  useStatefulCollection,
} from '@cerberus-design/react'


export function StartIconDemo() {
  const { collection, handleInputChange } = useStatefulCollection(items)

  return (
    <Box w="1/2">
      <Combobox
        collection={collection}
        label="Select Relative"
        onInputValueChange={handleInputChange}
        openOnClick
        placeholder="Choose option"
        startIcon={<Search />}
      >
        <For
          each={collection.items}
          fallback={
            <VStack paddingBlock="6" w="full">
              <Text textAlign="center" textStyle="label-sm">
                No results found
              </Text>
            </VStack>
          }
        >
          {(item) => (
            <ComboItemWithIndicator key={item.value} item={item}>
              <ComboItemText>{item.label}</ComboItemText>
            </ComboItemWithIndicator>
          )}
        </For>
      </Combobox>
    </Box>
  )
}
```


## Sizes

The `Combobox` component supports sizes: `sm` to `lg`. The default is `md`.


```tsx
'use client'


import {
  Combobox,
  ComboboxProps,
  ComboItemText,
  ComboItemWithIndicator,
  For,
  Text,
  useStatefulCollection,
} from '@cerberus-design/react'



export function SizeDemo() {
  return (
    <Stack gap="md" w="3/4">
      <For each={sizes}>{(size) => <SizeBox key={String(size)} size={size} />}</For>
    </Stack>
  )
}

interface SizeBoxProps<T> {
  size: ComboboxProps<T>['size']
}

export function SizeBox<T>(props: SizeBoxProps<T>) {
  const { collection, handleInputChange } = useStatefulCollection(items)

  return (
    <Combobox
      collection={collection}
      label={`Size: ${props.size}`}
      onInputValueChange={handleInputChange}
      placeholder="Type to search"
      size={props.size}
    >
      <For
        each={collection.items}
        fallback={
          <VStack paddingBlock="6" w="full">
            <Text textAlign="center" textStyle="label-sm">
              No results found
            </Text>
          </VStack>
        }
      >
        {(item) => (
          <ComboItemWithIndicator key={item.value} item={item}>
            <ComboItemText>{item.label}</ComboItemText>
          </ComboItemWithIndicator>
        )}
      </For>
    </Combobox>
  )
}
```


## With Field

Wrap the `Combobox` component with the `Field` component to add additional functionality such as error and helper text when using it in a form.


```tsx
'use client'


import {
  Combobox,
  ComboItemText,
  ComboItemWithIndicator,
  Field,
  For,
  Text,
  useStatefulCollection,
} from '@cerberus-design/react'


export function FieldDemo() {
  const { collection, handleInputChange } = useStatefulCollection(items)

  return (
    <Box w="1/2">
      <Field
        label="Select Relative"
        helperText="This is saved to your profile"
        errorText="You must select something."
        required
      >
        <Combobox
          collection={collection}
          onInputValueChange={handleInputChange}
          placeholder="Choose option"
        >
          <For
            each={collection.items}
            fallback={
              <VStack paddingBlock="6" w="full">
                <Text textAlign="center" textStyle="label-sm">
                  No results found
                </Text>
              </VStack>
            }
          >
            {(item) => (
              <ComboItemWithIndicator key={item.value} item={item}>
                <ComboItemText>{item.label}</ComboItemText>
              </ComboItemWithIndicator>
            )}
          </For>
        </Combobox>
      </Field>
    </Box>
  )
}
```


## Context

Access the combobox's state with `ComboboxContext` or the `useComboboxContext` hook—useful for displaying the selected value or building custom UI.

<NoteAdmonition description="Since combobox is an abstracted API, you'll need to build your own to obtain the context as we do in the example below." />


```tsx
'use client'



import {
  ComboboxParts,
  ComboItemText,
  ComboItemWithIndicator,
  For,
  Text,
  UseComboboxContext,
  useStatefulCollection,
} from '@cerberus-design/react'


export function ContextDemo() {
  const { collection, handleInputChange } = useStatefulCollection(items)

  return (
    <Stack w="1/2">
      <ComboboxParts.Root
        collection={collection}
        onInputValueChange={handleInputChange}
        placeholder="Choose option"
      >
        <ComboboxParts.Context>
          {(context: UseComboboxContext<(typeof collection.items)[number]>) => (
            <Text mb="md">Selected: {context.valueAsString || 'None'}</Text>
          )}
        </ComboboxParts.Context>

        <ComboboxParts.Label>Select Relative</ComboboxParts.Label>

        <ComboboxParts.Control>
          <ComboboxParts.Input />

          <ComboboxParts.ClearTrigger>
            <Close />
          </ComboboxParts.ClearTrigger>
          <ComboboxParts.Trigger>
            <ChevronDown />
          </ComboboxParts.Trigger>
        </ComboboxParts.Control>

        <ComboboxParts.Positioner>
          <ComboboxParts.Content>
            <For
              each={collection.items}
              fallback={
                <VStack paddingBlock="6" w="full">
                  <Text textAlign="center" textStyle="label-sm">
                    No results found
                  </Text>
                </VStack>
              }
            >
              {(item) => (
                <ComboItemWithIndicator key={item.value} item={item}>
                  <ComboItemText>{item.label}</ComboItemText>
                </ComboItemWithIndicator>
              )}
            </For>
          </ComboboxParts.Content>
        </ComboboxParts.Positioner>
      </ComboboxParts.Root>
    </Stack>
  )
}
```


## Grouped Items

To group items, use the `ComboItemGroup` component (not ComboboxItemGroup).


```tsx
'use client'



import {
  Combobox,
  ComboItemGroup,
  ComboItemText,
  ComboItemWithIndicator,
  For,
  Text,
  useStatefulCollection,
} from '@cerberus-design/react'


export function GroupedItemsDemo() {
  const { collection, handleInputChange } = useStatefulCollection(items)

  return (
    <Box w="1/2">
      <Combobox
        collection={collection}
        label="Select Relative"
        onInputValueChange={handleInputChange}
        placeholder="Choose option"
        startIcon={<Search />}
      >
        <ComboItemGroup label="The fam">
          <For
            each={collection.items}
            fallback={
              <VStack paddingBlock="6" w="full">
                <Text textAlign="center" textStyle="label-sm">
                  No results found
                </Text>
              </VStack>
            }
          >
            {(item) => (
              <ComboItemWithIndicator key={item.value} item={item}>
                <ComboItemText>{item.label}</ComboItemText>
              </ComboItemWithIndicator>
            )}
          </For>
        </ComboItemGroup>
      </Combobox>
    </Box>
  )
}
```


## Async Loading

Combine the collection with a [query](/docs/signals/create-query) to load data asynchronously with signal-based speed.


```tsx
'use client'



import {
  ComboItemText,
  ComboItemWithIndicator,
  Combobox,
  ComboboxInputValueChangeDetails,
  For,
  Spinner,
  Text,
  createListCollection,
} from '@cerberus-design/react'



function useDeferredValue() {
  // Use native React state and transitions for loading state to override Suspsense
  const [inputValue, setInputValue] = useState<string>('')
  const [pending, startTransition] = useTransition()
  return {
    inputValue,
    setInputValue,
    pending,
    startTransition,
  }
}

function AsyncCombobox() {
  const { inputValue, setInputValue, pending, startTransition } = useDeferredValue()
  const data = useQuery(queryList(inputValue))

  const collection = createListCollection<Character>({
    items: data,
    itemToString: (item) => item.name,
    itemToValue: (item) => item.url,
  })

  const handleInputChange = (details: ComboboxInputValueChangeDetails) => {
    if (details.reason === 'input-change') {
      startTransition(() => {
        setInputValue(details.inputValue)
      })
    }
  }

  return (
    <Combobox
      collection={collection}
      label="Select Star Wars Character"
      onInputValueChange={handleInputChange}
      placeholder="Type to search or choose an option"
      startIcon={
        pending ? (
          <Square size="4">
            <Spinner />
          </Square>
        ) : (
          <Search />
        )
      }
    >
      <For
        each={collection.items}
        fallback={
          <VStack paddingBlock="6" w="full">
            <Text textAlign="center" textStyle="label-sm">
              No results found
            </Text>
          </VStack>
        }
      >
        {(item) => (
          <ComboItemWithIndicator key={item.name} item={item}>
            <ComboItemText>{item.name}</ComboItemText>
          </ComboItemWithIndicator>
        )}
      </For>
    </Combobox>
  )
}

export function LoadingDemo() {
  return (
    <Box w="1/2">
      <Suspense fallback="...loading">
        <AsyncCombobox />
      </Suspense>
    </Box>
  )
}

// Factories

interface Character {
  name: string
  height: string
  mass: string
  created: string
  edited: string
  url: string
}

const queryList = createQuery(async (inputValue: string) => {
  try {
    const response = await db.searchCharacters(inputValue)
    return response.results
  } catch (error) {
    console.error(error)
    return []
  }
}, 'queryList')

// API

const db = {
  searchCharacters: async (inputValue: string) => {
    const response = await fetch(
      `https://swapi.py4e.com/api/people/?search=${inputValue ?? ''}`,
    )
    return await response.json()
  },
}
```


## Highlight Matching Text

Combine the `ComboItemText` component with the `Highlight` component to highlight matching text in the dropdown.


```tsx
'use client'


import {
  Combobox,
  ComboboxContext,
  ComboItemText,
  ComboItemWithIndicator,
  For,
  Highlight,
  Text,
  useStatefulCollection,
} from '@cerberus-design/react'


export function HighlightDemo() {
  const { collection, handleInputChange } = useStatefulCollection(items)

  return (
    <Box w="1/2">
      <Combobox
        collection={collection}
        label="Select Relative"
        onInputValueChange={handleInputChange}
        placeholder="Choose option"
      >
        <For
          each={collection.items}
          fallback={
            <VStack paddingBlock="6" w="full">
              <Text textAlign="center" textStyle="label-sm">
                No results found
              </Text>
            </VStack>
          }
        >
          {(item) => (
            <ComboItemWithIndicator key={item.value} item={item}>
              <ComboItemText>
                <ComboboxContext>
                  {(context) => (
                    <Highlight
                      text={item.label}
                      query={context.inputValue}
                      ignoreCase
                    />
                  )}
                </ComboboxContext>
              </ComboItemText>
            </ComboItemWithIndicator>
          )}
        </For>
      </Combobox>
    </Box>
  )
}
```


## Creatable

Allow users to create new options when their search doesn't match any existing items. This is useful for tags, categories, or other custom values.


```tsx
'use client'



import {
  Combobox,
  ComboboxInputValueChangeDetails,
  ComboboxOpenChangeDetails,
  ComboboxValueChangeDetails,
  ComboItemText,
  ComboItemWithIndicator,
  For,
  Show,
  Tag,
  Text,
  useFilter,
  useListCollection,
} from '@cerberus-design/react'



interface Item {
  label: string
  value: string
  __new__?: boolean
}

const NEW_OPTION_VALUE = '[[new]]'

const api = {
  create: (value: string): Item => ({ label: value, value: NEW_OPTION_VALUE }),
  isNew: (value: string) => value === NEW_OPTION_VALUE,
  replaceValue: (values: string[], value: string) => {
    return values.map((v) => (v === NEW_OPTION_VALUE ? value : v))
  },
  getNewOptionData: (inputValue: string): Item => ({
    label: inputValue,
    value: inputValue,
    __new__: true,
  }),
}

export function CreatableDemo() {
  const [selectedValue, setSelectedValue] = useSignal<string[]>([])
  const [inputValue, setInputValue] = useSignal('')

  const { contains } = useFilter({ sensitivity: 'base' })
  const { collection, filter, upsert, update, remove } = useListCollection<Item>({
    initialItems: [
      { label: 'Bug', value: 'bug' },
      { label: 'Feature', value: 'feature' },
      { label: 'Enhancement', value: 'enhancement' },
      { label: 'Documentation', value: 'docs' },
    ],
    filter: contains,
  })

  const isValidNewOption = (inputValue: string) => {
    const exactOptionMatch =
      collection.filter((item) => item.toLowerCase() === inputValue.toLowerCase())
        .size > 0
    return !exactOptionMatch && inputValue.trim().length > 0
  }

  const handleInputChange = ({
    inputValue,
    reason,
  }: ComboboxInputValueChangeDetails) => {
    if (reason === 'input-change' || reason === 'item-select') {
      flushSync(() => {
        if (isValidNewOption(inputValue)) {
          upsert(NEW_OPTION_VALUE, api.create(inputValue))
        } else if (inputValue.trim().length === 0) {
          remove(NEW_OPTION_VALUE)
        }
      })
      filter(inputValue)
    }
    setInputValue(inputValue)
  }

  const handleOpenChange = ({ reason }: ComboboxOpenChangeDetails) => {
    if (reason === 'trigger-click') {
      filter('')
    }
  }

  const handleValueChange = ({ value }: ComboboxValueChangeDetails) => {
    setSelectedValue(api.replaceValue(value, inputValue))
    if (value.includes(NEW_OPTION_VALUE)) {
      console.log('New Option Created', inputValue)
      update(NEW_OPTION_VALUE, api.getNewOptionData(inputValue))
    }
  }

  return (
    <Box w="1/2">
      <Combobox
        allowCustomValue
        collection={collection}
        label="Select Relative"
        onOpenChange={handleOpenChange}
        onInputValueChange={handleInputChange}
        onValueChange={handleValueChange}
        placeholder="Choose option"
        value={selectedValue}
      >
        <For
          each={collection.items}
          fallback={
            <VStack paddingBlock="6" w="full">
              <Text textAlign="center" textStyle="label-sm">
                No results found
              </Text>
            </VStack>
          }
        >
          {(item) => (
            <ComboItemWithIndicator key={item.value} item={item}>
              <Show
                when={api.isNew(item.value)}
                fallback={<ComboItemText>{item.label}</ComboItemText>}
              >
                {() => (
                  <ComboItemText textStyle="label-sm">
                    + Create &quot;{item.label}&quot;
                  </ComboItemText>
                )}
              </Show>

              <Show when={item.__new__}>
                {() => (
                  <Tag palette="success" usage="outlined">
                    New <Corn />
                  </Tag>
                )}
              </Show>
            </ComboItemWithIndicator>
          )}
        </For>
      </Combobox>
    </Box>
  )
}
```


## Customizing


```tsx
'use client'



import {
  ComboboxParts,
  For,
  Portal,
  Text,
  useStatefulCollection,
} from '@cerberus-design/react'


export function CustomDemo() {
  const { collection, handleInputChange } = useStatefulCollection(items)

  return (
    <Box w="1/2">
      <ComboboxParts.Root
        collection={collection}
        onInputValueChange={handleInputChange}
        transform="skewX(-10deg)"
      >
        <ComboboxParts.Label textTransform="uppercase">
          Custom label
        </ComboboxParts.Label>

        <ComboboxParts.Control>
          <ComboboxParts.Input />

          <ComboboxParts.Trigger>
            <ChevronDownOutline />
          </ComboboxParts.Trigger>
        </ComboboxParts.Control>

        <Portal>
          <ComboboxParts.Positioner>
            <ComboboxParts.Content>
              <For
                each={collection.items}
                fallback={
                  <VStack paddingBlock="6" w="full">
                    <Text textAlign="center" textStyle="label-sm">
                      No results found
                    </Text>
                  </VStack>
                }
              >
                {(item) => (
                  <ComboboxParts.Item key={item.value} item={item}>
                    <ComboboxParts.ItemText fontSize="xl">
                      {item.label}
                    </ComboboxParts.ItemText>
                    <ComboboxParts.ItemIndicator>🔥</ComboboxParts.ItemIndicator>
                  </ComboboxParts.Item>
                )}
              </For>
            </ComboboxParts.Content>
          </ComboboxParts.Positioner>
        </Portal>
      </ComboboxParts.Root>
    </Box>
  )
}
```


## Guides

### Router Links

Customize the `navigate` prop on `Combobox` to integrate with your router. Using Tanstack Router:


```tsx
// Source available in static configuration: {DEMOS.linksMeta}
```


### Custom Objects

By default, the combobox collection expects an array of objects with label and value properties. In some cases, you may need to deal with custom objects.

Use the `itemToString` and `itemToValue` props to map the custom object to the required interface.


```tsx
// Source available in static configuration: {DEMOS.objectsMeta}
```


### Type Safety

The `ComboboxRootProps` type enables you to create typed wrapper components that maintain full type safety for collection items.


```tsx
// Source available in static configuration: {DEMOS.typeMeta}
```


### Large Datasets

The recommended way of managing large lists is to use the `limit` property on the `useListCollection` hook. This will limit the number of rendered items in the DOM to improve performance.


```tsx
// Source available in static configuration: {DEMOS.largeMeta}
```


### Available Size

The following css variables are exposed to the `ComboboxPositioner` which you can use to style the `ComboboxContent`.


```tsx
// Source available in static configuration: {DEMOS.varsMeta}
```

<br />

For example, if you want to make sure the maximum height doesn't exceed the available height, you can use the following:


```tsx
// Source available in static configuration: {DEMOS.styleMeta}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the Combobox.

| Component              | Description                                                 |
| ---------------------- | ----------------------------------------------------------- |
| ComboboxRoot           | The context provider for the combobox family                |
| ComboboxLabel          | The label that appears above the combobox input             |
| ComboboxControl        | The wrapper to the combobox trigger that opens the dropdown |
| ComboboxInput          | The input field of the combobox                             |
| ComboboxTrigger        | he trigger that opens the dropdown                          |
| ComboboxClearTrigger   | The trigger that clears the selected value                  |
| ComboboxPositioner     | The wrapper that positions the dropdown                     |
| ComboboxContent        | The content of the dropdown (i.e. the container itself)     |
| ComboboxItemGroup      | The group of options in the dropdown                        |
| ComboboxItemGroupLabel | The label for the group of options                          |
| ComboboxItem           | The option in the dropdown                                  |
| ComboboxItemText       | The text label of the option                                |
| ComboboxItemIndicator  | The indicator shown when the option is selected             |

## API

### Combobox

The `Combobox` component is an abstraction of our primitives and accepts the following props:

| Name        | Default | Description                                    |
| ----------- | ------- | ---------------------------------------------- |
| `size`      | `md`    | The size of the combobox.                      |
| `startIcon` |         | The icon to display at the start of the input. |

The `Combobox` component also accepts all the props of the [`ComboboxRoot` primitive props](https://ark-ui.com/react/docs/components/combobox#api-reference)

### ItemWithIndicator

The `ItemWithIndicator` component is an abstraction of our primitives and accepts all the props of the [`ComboboxItem` primitive props](https://ark-ui.com/react/docs/components/combobox#api-reference)

### ComboItemGroup

The `ComboItemGroup` component is an abstraction of our primitives and accepts the following props:

| Name    | Default | Description             |
| ------- | ------- | ----------------------- |
| `label` |         | The label of the group. |

The `ComboItemGroup` component is an abstraction of our primitives and accepts all the props of the [`ComboboxItemGroup` primitive props](https://ark-ui.com/react/docs/components/combobox#api-reference)

## Primitive API

### Root Props

| Prop                      | Type                                           | Required | Description                                                                                                                                                                                                                          |
| ------------------------- | ---------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `collection`              | `ListCollection<T>`                            | Yes      | The collection of items                                                                                                                                                                                                              |
| `allowCustomValue`        | `boolean`                                      | No       | Whether to allow typing custom values in the input                                                                                                                                                                                   |
| `alwaysSubmitOnEnter`     | `boolean`                                      | No       | Whether to always submit on Enter key press, even if popup is open.                                                                                                                                                                  |
| `asChild`                 | `boolean`                                      | No       | Use the provided child element as the default rendered element, combining their props and behavior.                                                                                                                                  |
| `autoFocus`               | `boolean`                                      | No       | Whether to autofocus the input on mount                                                                                                                                                                                              |
| `closeOnSelect`           | `boolean`                                      | No       | Whether to close the combobox when an item is selected.                                                                                                                                                                              |
| `autoFocus`               | `boolean`                                      | No       | Whether to autofocus the input on mount                                                                                                                                                                                              |
| `closeOnSelect`           | `boolean`                                      | No       | Whether to close the combobox when an item is selected.                                                                                                                                                                              |
| `composite`               | `boolean`                                      | No       | Whether the combobox is a composed with other composite widgets like tabs                                                                                                                                                            |
| `defaultHighlightedValue` | `string`                                       | No       | The initial highlighted value of the combobox when rendered. Use when you don't need to control the highlighted value of the combobox.                                                                                               |
| `defaultInputValue`       | `string`                                       | No       | The initial value of the combobox's input when rendered. Use when you don't need to control the value of the combobox's input.                                                                                                       |
| `defaultOpen`             | `boolean`                                      | No       | The initial open state of the combobox when rendered. Use when you don't need to control the open state of the combobox.                                                                                                             |
| `defaultValue`            | `string[]`                                     | No       | The initial value of the combobox's selected items when rendered. Use when you don't need to control the value of the combobox's selected items.                                                                                     |
| `disabled`                | `boolean`                                      | No       | Whether the combobox is disabled                                                                                                                                                                                                     |
| `disableLayer`            | `boolean`                                      | No       | Whether to disable registering this a dismissable layer                                                                                                                                                                              |
| `form`                    | `string`                                       | No       | The associate form of the combobox.                                                                                                                                                                                                  |
| `highlightedValue`        | `string`                                       | No       | The controlled highlighted value of the combobox                                                                                                                                                                                     |
| `id`                      | `string`                                       | No       | The unique identifier of the machine.                                                                                                                                                                                                |
| `ids`                     | `Partial<Parts>`                               | No       | The ids of the elements in the combobox. Useful for composition.                                                                                                                                                                     |
| `immediate`               | `boolean`                                      | No       | Whether to synchronize the present change immediately or defer it to the next frame                                                                                                                                                  |
| `inputBehavior`           | `'none'  \| 'autohighlight' \| 'autocomplete'` | No       | Defines the auto-completion behavior of the combobox. `autohighlight`: The first focused item is highlighted as the user types, `autocomplete`: Navigating the listbox with the arrow keys selects the item and the input is updated |
| `inputValue`              | `string`                                       | No       | The controlled value of the combobox's input                                                                                                                                                                                         |
| `invalid`                 | `boolean`                                      | No       | Whether the combobox is invalid                                                                                                                                                                                                      |
| `lazyMount`               | `boolean`                                      | No       | Whether to enable lazy mounting                                                                                                                                                                                                      |
| `loopFocus`               | `boolean`                                      | No       | Whether to loop the keyboard navigation through the items                                                                                                                                                                            |
| `multiple`                | `boolean`                                      | No       | Whether to allow multiple selection. **Good to know:** When `multiple` is `true`, the `selectionBehavior` is automatically set to `clear`. It is recommended to render the selected items in a separate container.                   |
| `name`                    | `string`                                       | No       | The `name` attribute of the combobox's input. Useful for form submission                                                                                                                                                             |
| `navigate`                | `(details: NavigateDetails) => void`           | No       | Function to navigate to the selected item                                                                                                                                                                                            |
| `onExitComplete`          | `VoidFunction`                                 | No       | Function called when the animation ends in the closed state                                                                                                                                                                          |
| `onFocusOutside`          | `(event: FocusOutsideEvent) => void`           | No       | Function called when the focus is moved outside the component                                                                                                                                                                        |
| `onHighlightChange`       | `(details: HighlightChangeDetails<T>) => void` | No       | Function called when an item is highlighted using the pointer or keyboard navigation.                                                                                                                                                |
| `onInputValueChange`      | `(details: InputValueChangeDetails) => void`   | No       | Function called when the input's value changes                                                                                                                                                                                       |
| `onInteractOutside`       | `(event: InteractOutsideEvent) => void`        | No       | Function called when an interaction happens outside the component                                                                                                                                                                    |
| `onOpenChange`            | `(details: OpenChangeDetails) => void`         | No       | Function called when the popup is opened                                                                                                                                                                                             |
| `onPointerDownOutside`    | `(event: PointerDownOutsideEvent) => void`     | No       | Function called when the pointer is pressed down outside the component                                                                                                                                                               |
| `onSelect`                | `(details: SelectionDetails) => void`          | No       | Function called when an item is selected                                                                                                                                                                                             |
| `onValueChange`           | `(details: ValueChangeDetails<T>) => void`     | No       | Function called when a new item is selected                                                                                                                                                                                          |
| `open`                    | `boolean`                                      | No       | The controlled open state of the combobox                                                                                                                                                                                            |
| `openOnChange`            | `boolean`                                      | No       | Whether to show the combobox when the input value changes                                                                                                                                                                            |
| `openOnClick`             | `boolean`                                      | No       | Whether to open the combobox popup on initial click on the input                                                                                                                                                                     |
| `openOnKeyPress`          | `boolean`                                      | No       | Whether to open the combobox on arrow key press                                                                                                                                                                                      |
| `placeholder`             | `string`                                       | No       | The placeholder text of the combobox's input                                                                                                                                                                                         |
| `positioning`             | `PositioningOptions`                           | No       | The positioning options to dynamically position the menu                                                                                                                                                                             |
| `present`                 | `boolean`                                      | No       | Whether the node is present (controlled by the user)                                                                                                                                                                                 |
| `readOnly`                | `boolean`                                      | No       | Whether the combobox is readonly. This puts the combobox in a "non-editable" mode but the user can still interact with it                                                                                                            |
| `required`                | `boolean`                                      | No       | Whether the combobox is required                                                                                                                                                                                                     |
| `scrollToIndexFn`         | `(details: ScrollToIndexDetails) => void`      | No       | Function to scroll to a specific index                                                                                                                                                                                               |
| `selectionBehavior`       | `'clear' \| 'replace' \| 'preserve'`           | No       | The behavior of the combobox input when an item is selected. `replace`: The selected item string is set as the input value, `clear`: The input value is cleared, `preserve`: The input value is preserved                            |
| `skipAnimationOnMount`    | `boolean`                                      | No       | Whether to allow the initial presence animation.                                                                                                                                                                                     |
| `translations`            | `IntlTranslations`                             | No       | Specifies the localized strings that identifies the accessibility elements and their states                                                                                                                                          |
| `unmountOnExit`           | `boolean`                                      | No       | Whether to unmount on exit.                                                                                                                                                                                                          |
| `value` \| `string[]`     | No                                             | No       | The controlled value of the combobox's selected items                                                                                                                                                                                |

### Root Data Attributes:

| Attribute         | Value                  |
| ----------------- | ---------------------- |
| `[data-scope]`    | combobox               |
| `[data-part]`     | root                   |
| `[data-invalid]`  | Present when invalid   |
| `[data-readonly]` | Present when read-only |

### ClearTrigger Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### ClearTrigger Data Attributes:

| Attribute        | Value                |
| ---------------- | -------------------- |
| `[data-scope]`   | combobox             |
| `[data-part]`    | clear-trigger        |
| `[data-invalid]` | Present when invalid |

### Content Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Content Data Attributes:

| Attribute           | Value                             |
| ------------------- | --------------------------------- |
| `[data-scope]`      | combobox                          |
| `[data-part]`       | content                           |
| `[data-state]`      | "open" \| "closed"                |
| `[data-nested]`     | listbox                           |
| `[data-has-nested]` | listbox                           |
| `[data-placement]`  | The placement of the content      |
| `[data-empty]`      | Present when the content is empty |

#### Content CSS Variables:

| Variable               | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `--layer-index`        | The index of the dismissable in the layer stack |
| `--nested-layer-count` | The number of nested comboboxs                  |

### Control Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Control Data Attributes:

| Attribute         | Value                 |
| ----------------- | --------------------- |
| `[data-scope]`    | combobox              |
| `[data-part]`     | control               |
| `[data-state]`    | "open" \| "closed"    |
| `[data-focus]`    | Present when focused  |
| `[data-disabled]` | Present when disabled |
| `[data-invalid]`  | Present when invalid  |

### Input Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Input Data Attributes:

| Attribute          | Value                |
| ------------------ | -------------------- |
| `[data-scope]`     | combobox             |
| `[data-part]`      | input                |
| `[data-invalid]`   | Present when invalid |
| `[data-autofocus]` |                      |
| `[data-state]`     | "open" \| "closed"   |

#### ItemGroupLabel Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

### ItemGroup Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### ItemGroup Data Attributes:

| Attribute      | Value                             |
| -------------- | --------------------------------- |
| `[data-scope]` | combobox                          |
| `[data-part]`  | item-group                        |
| `[data-empty]` | Present when the content is empty |

### ItemIndicator Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### ItemIndicator Data Attributes:

| Attribute      | Value                    |
| -------------- | ------------------------ |
| `[data-scope]` | combobox                 |
| `[data-part]`  | item-indicator           |
| `[data-state]` | "checked" \| "unchecked" |

### Item Props:

| Prop           | Type      | Required | Description                                                                                         |
| -------------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild`      | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |
| `item`         | `any`     | No       | The item to render                                                                                  |
| `persistFocus` | `boolean` | No       | Whether hovering outside should clear the highlighted state                                         |

#### Item Data Attributes:

| Attribute            | Value                    |
| -------------------- | ------------------------ |
| `[data-scope]`       | combobox                 |
| `[data-part]`        | item                     |
| `[data-highlighted]` | Present when highlighted |
| `[data-state]`       | "checked" \| "unchecked" |
| `[data-disabled]`    | Present when disabled    |
| `[data-value]`       | The value of the item    |

### ItemText Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### ItemText Data Attributes:

| Attribute            | Value                    |
| -------------------- | ------------------------ |
| `[data-scope]`       | combobox                 |
| `[data-part]`        | item-text                |
| `[data-state]`       | "checked" \| "unchecked" |
| `[data-disabled]`    | Present when disabled    |
| `[data-highlighted]` | Present when highlighted |

### Label Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Label Data Attributes:

| Attribute         | Value                  |
| ----------------- | ---------------------- |
| `[data-scope]`    | combobox               |
| `[data-part]`     | label                  |
| `[data-readonly]` | Present when read-only |
| `[data-disabled]` | Present when disabled  |
| `[data-invalid]`  | Present when invalid   |
| `[data-required]` | Present when required  |
| `[data-focus]`    | Present when focused   |

### List Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### List Data Attributes:

| Attribute      | Value                             |
| -------------- | --------------------------------- |
| `[data-scope]` | combobox                          |
| `[data-part]`  | list                              |
| `[data-empty]` | Present when the content is empty |

### Positioner Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Positioner CSS Variables:

| Variable             | Description                         |
| -------------------- | ----------------------------------- |
| `--reference-width`  | The width of the reference element  |
| `--reference-height` | The height of the root              |
| `--available-width`  | The available width in viewport     |
| `--available-height` | The available height in viewport    |
| `--x`                | The x position for transform        |
| `--y`                | The y position for transform        |
| `--z-index`          | The z-index value                   |
| `--transform-origin` | The transform origin for animations |

### RootProvider Props:

| Prop                   | Type                   | Required | Description                                                                                         |
| ---------------------- | ---------------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `value`                | `UseComboboxReturn<T>` | Yes      |                                                                                                     |
| `asChild`              | `boolean`              | No       | Use the provided child element as the default rendered element, combining their props and behavior. |
| `immediate`            | `boolean`              | No       | Whether to synchronize the present change immediately or defer it to the next frame                 |
| `lazyMount`            | `boolean`              | No       | Whether to enable lazy mounting                                                                     |
| `onExitComplete`       | `VoidFunction`         | No       | Function called when the animation ends in the closed state                                         |
| `present`              | `boolean`              | No       | Whether the node is present (controlled by the user)                                                |
| `skipAnimationOnMount` | `boolean`              | No       | Whether to allow the initial presence animation.                                                    |
| `unmountOnExit`        | `boolean`              | No       | Whether to unmount on exit.                                                                         |

### Trigger Props:

| Prop        | Type      | Required | Description                                                                                         |
| ----------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild`   | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |
| `focusable` | `boolean` | No       | Whether the trigger is focusable                                                                    |

#### Trigger Data Attributes:

| Attribute          | Value                  |
| ------------------ | ---------------------- |
| `[data-scope]`     | combobox               |
| `[data-part]`      | trigger                |
| `[data-state]`     | "open" \| "closed"     |
| `[data-invalid]`   | Present when invalid   |
| `[data-focusable]` |                        |
| `[data-readonly]`  | Present when read-only |
| `[data-disabled]`  | Present when disabled  |

## Hooks

### useStatefulCollection

The `useStatefulCollection` function is a utility hook that creates a collection of options and filters the list based on the user input.

#### Returns

| Name              | Description                                    |
| ----------------- | ---------------------------------------------- |
| collection        | The collection of options.                     |
| filterChars       | The filter value split into an Array of chars. |
| handleInputChange | The function to pass to `onInputValueChange`.  |

### Parts

The `ComboboxParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the ComboboxParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name           | Description                                                                            |
| -------------- | -------------------------------------------------------------------------------------- |
| Root           | The `ComboboxRoot` component which is the Provider for the family.                     |
| Label          | The `ComboboxLabel` component which displays the label.                                |
| Control        | The `ComboboxControl` component which is the container for the visual field.           |
| Input          | The `ComboboxInput` component which is the visual field.                               |
| Trigger        | The `ComboboxTrigger` component which is the trigger for the dropdown.                 |
| ClearTrigger   | The `ComboboxClearTrigger` component which is the trigger to clear the value.          |
| Positioner     | The `ComboboxPositioner` component which is controls the positioning for the dropdown. |
| Content        | The `ComboboxContent` component which is the dropdown itself.                          |
| ItemGroup      | The `ComboboxItemGroup` component which is the group of options in the dropdown.       |
| ItemGroupLabel | The `ComboboxItemGroupLabel` component which is the label for the group of options.    |
| Item           | The `ComboboxItem` component which is the option in the dropdown.                      |
| ItemText       | The `ComboboxItemText` component which is the text label of the option.                |
| ItemIndicator  | The `ComboboxItemIndicator` component which displays based on the `checked` state.     |


---
## composition

---
---



## Composition

<strong>Learn how to compose components in Cerberus.</strong>

## The `as` Prop

Used to change the underlying HTML element that a React component renders. It
provides a straightforward way to change the underlying element while retaining
the component's functionality.

```tsx
<Text as="h3">Hello, world!</Text>
```

<WarningAdmonition description={<>This is only available for the <code>Text</code> component which is a wrapper around our text-related patterns.</>} />

## The `asChild` Prop

Used to compose a component's functionality onto its child element. This
approach, inspired by
[Radix UI](https://www.radix-ui.com/primitives/docs/utilities/slot), offers
maximum flexibility.

```tsx
<Button asChild>
  <Link href="/some-page">Open</Link>
</Button>
```

In this example, the `asChild` prop allows the link to be used as the
button (e.g., a button-styled link).

## Best Practices

To avoid common pitfalls when using the `as` and `asChild` props, there are a
few best practices to consider:

- **Forward Refs:** Ensure that the underlying component forwards the ref passed
  to it properly.
- **Spread Props:** Ensure that the underlying component spreads the props
  passed to it.

### Advanced Usage Example

```tsx
const MyComponent = forwardRef((props, ref) => {
  return <Box ref={ref} {...props} />
})

<Button asChild>
  <MyComponent> Click me </MyComponent>
</Button>
```


---
## confirm-modal

---
title: Confirm Modal
description: 'The Confirm Modal component provides a way to confirm actions with users, ensuring they are aware of the consequences before proceeding.'
npm: '@cerberus-design/react'
source: 'context/confirm-modal.tsx'
recipe: 'slots/dialog.ts'
ark: 'dialog'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The `ConfirmModal` component is a controlled abstraction of the [Dialog](/docs/components/dialog).


```tsx
'use client'


import {
  Button,
  ConfirmModal,
  Show,
  Text,
  useConfirmModal,
} from '@cerberus-design/react'



export function BasicDemo() {
  return (
    <ConfirmModal>
      <NonDestructiveFeature />
    </ConfirmModal>
  )
}

function NonDestructiveFeature() {
  const confirm = useConfirmModal()
  const [consent, setConsent] = useSignal<boolean | null>(null)

  const handleClick = async () => {
    const userConsent = await confirm.show({
      heading: 'Add new payment method?',
      description: (
        <>
          This will add a new payment method to your account to be billed for future
          purchases. <Link href="#">Learn more</Link>.
        </>
      ),
      actionText: 'Yes, add payment method',
      cancelText: 'No, cancel',
    })
    setConsent(userConsent)
  }

  return (
    <HStack gap="md">
      <HStack gap="md">
        <Button onClick={handleClick}>Confirm</Button>
      </HStack>

      <Show when={consent !== null}>
        <Text as="small" textStyle="label-sm">
          User consent:{' '}
          <Text as="span" fontSize="xs" textStyle="mono-xs">
            {JSON.stringify(consent)}
          </Text>
        </Text>
      </Show>
    </HStack>
  )
}
```


## Destructive

To show a destructive confirm modal, set the `kind` prop in the options to `'destructive'`.


```tsx
'use client'


import {
  Button,
  ConfirmModal,
  Show,
  Text,
  useConfirmModal,
} from '@cerberus-design/react'


export function DestructiveDemo() {
  return (
    <ConfirmModal>
      <DestructiveFeature />
    </ConfirmModal>
  )
}

function DestructiveFeature() {
  const confirm = useConfirmModal()
  const [consent, setConsent] = useSignal<boolean | null>(null)

  const handleClick = async () => {
    const userConsent = await confirm.show({
      kind: 'destructive',
      heading: 'Remove payment method?',
      description: 'This is a permanent action and cannot be undone.',
      actionText: 'Yes, delete',
      cancelText: 'Cancel',
    })
    setConsent(userConsent)
  }

  return (
    <HStack gap="md">
      <HStack gap="md">
        <Button palette="danger" onClick={handleClick}>
          Remove
        </Button>
      </HStack>

      <Show when={consent !== null}>
        <Text as="small" textStyle="label-sm">
          User consent:{' '}
          <Text as="span" fontSize="xs" textStyle="mono-xs">
            {JSON.stringify(consent)}
          </Text>
        </Text>
      </Show>
    </HStack>
  )
}
```


### No Avatar

To change the visibility of the avatar, set `showAvatar` to `false` in the options.


```tsx
'use client'


import {
  Button,
  ConfirmModal,
  Show,
  Text,
  useConfirmModal,
} from '@cerberus-design/react'



export function NoAvatarDemo() {
  return (
    <ConfirmModal>
      <Feature />
    </ConfirmModal>
  )
}

function Feature() {
  const confirm = useConfirmModal()
  const [consent, setConsent] = useSignal<boolean | null>(null)

  const handleClick = async () => {
    const userConsent = await confirm.show({
      showAvatar: false,
      heading: 'Add new payment method?',
      description: (
        <>
          This will add a new payment method to your account to be billed for future
          purchases. <Link href="#">Learn more</Link>.
        </>
      ),
      actionText: 'Yes, add payment method',
      cancelText: 'No, cancel',
    })
    setConsent(userConsent)
  }

  return (
    <HStack gap="md">
      <HStack gap="md">
        <Button onClick={handleClick}>Confirm</Button>
      </HStack>

      <Show when={consent !== null}>
        <Text as="small" textStyle="label-sm">
          User consent:{' '}
          <Text as="span" fontSize="xs" textStyle="mono-xs">
            {JSON.stringify(consent)}
          </Text>
        </Text>
      </Show>
    </HStack>
  )
}
```


## Primitives

The layers of the `ConfirmModal` which can be used to create a fully custom solution are the same as the [Dialog](/docs/components/dialog#primitives).

### Data Attributes

The primitives additionally use the same data attributes as the [Dialog](/docs/components/dialog#primitives).

## API

### ConfirmModal

The `ConfirmModal` component is an abstraction of the Dialog and accepts the same
props as the [`Dialog`](/docs/components/dialog#api) component.

### Show Method Options

The `show` method accepts the following options:

| Name          | Default           | Description                                                                        |
| ------------- | ----------------- | ---------------------------------------------------------------------------------- |
| `showAvatar`  | `true`            | Whether to show the avatar in the modal.                                           |
| `kind`        | `non-destructive` | The variant used to theme the modal.                                               |
| `heading`     |                   | The heading of the modal.                                                          |
| `description` |                   | The description of the modal. For non-destructive modals only, can be a ReactNode. |
| `actionText`  |                   | The text for the action button.                                                    |
| `cancelText`  |                   | The text for the cancel button.                                                    |


---
## container

---
title: Container
description:
  Used to constrain a content's width to the current breakpoint, while keeping
  it fluid.
panda: https://panda-css.com/docs/concepts/patterns#container
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The default `maxWidth` is `8xl` which maps to `90rem (1440px)`.


```tsx



export function BasicDemo() {
  return (
    <Container bgColor="page.surface.100">
      <DecorativeBox p="md">Content in a Container</DecorativeBox>
    </Container>
  )
}
```


### Sizes

Use the `maxWidth` prop to change the size of the container.


```tsx



function getText(size: string) {
  return `This is some text within a container of size ${size}.`
}

export function SizesDemo() {
  return (
    <VStack w="full">
      <Container maxW="1/4" px="2" w="full">
        <DecorativeBox px="md">{getText('1/4')}</DecorativeBox>
      </Container>

      <Container maxW="1/2" px="2" w="full">
        <DecorativeBox px="md">{getText('1/2')}</DecorativeBox>
      </Container>

      <Container maxW="3/4" px="2" w="full">
        <DecorativeBox px="md">{getText('3/4')}</DecorativeBox>
      </Container>

      <Container px="2" w="full">
        <DecorativeBox px="md">{getText('full')}</DecorativeBox>
      </Container>
    </VStack>
  )
}
```


## Props

The `Container` component accepts any CSS properties.


---
## cta-modal

---
title: 'CTA Modal'
description: 'A modal component for displaying call-to-action messages.'
npm: '@cerberus-design/react'
source: 'components/cta-dialog'
recipe: 'slots/dialog.ts'
ark: 'dialog'
---


import {
  OverviewPreview,
  WithLinksDemo,
  WithCustomDescriptionDemo,
} from '../components/cta-modal/static'

```ts

```

## Usage

To use the CTAModal, wrap your component with the `CTAModal` provider and use the `useCTAModal` hook to access the `show` method.

To create your actions, use the `createCTAModalActions` function.

}>
```tsx title="action-dialog.tsx"
'use client'




function CTAFeature() {
  const { show } = useCTAModal()

  const handleClick = useCallback(() => {
    show({
      heading: 'Copy or create a Cohort',
      description: 'Create a new cohort or copy an existing one.',
      actions: createCTAModalActions([
        {
          text: 'Create new',
          handleClick: () => alert('Create new'),
        },
        {
          text: 'Copy existing',
          handleClick: () => alert('Copy existing'),
        },
      ]),
    })
  }, [show])

  return (
    <HStack gap="4">
      <Button onClick={handleClick}>Update Cohorts</Button>
    </HStack>
  )
}
```
```tsx title="page.tsx"



function SomePage() {
  return(
    <CTAModal>
      <CTAFeature />
    </CTAModal>
  )
}
```


## With Links

To use links instead of buttons, pass your link components to the `createCTAModalActions` function.

}>
```tsx title="link-dialog.tsx"
'use client'




function CTALinkFeature() {
  const { show } = useCTAModal()

  const handleLinkClick = useCallback(() => {
    show({
      heading: 'Copy or create a Cohort',
      description: 'Create a new cohort or copy an existing one.',
      actions: createCTAModalActions([
        <Link key="cta:link:btn" href="/react/button">
          See Button Docs
        </Link>,
        <Link key="cta:link:docs" href="/react/dialog">
          See Dialog Docs
        </Link>,
      ]),
    })
  }, [show])

  return (
    <HStack gap="4">
      <Button onClick={handleLinkClick}>Update Cohorts</Button>
    </HStack>
  )
}
```
```tsx title="page.tsx"



function SomePage() {
  return(
    <CTAModal>
      <CTALinkFeature />
    </CTAModal>
  )
}
```


## With Content

To use a custom content component, pass your custom component to the `content` prop of the `show` method.

}>
```tsx title="custom-description-dialog.tsx"
'use client'




function CTAFeature() {
  const { show } = useCTAModal()

  const handleClick = useCallback(() => {
    show({
      heading: 'Copy or create a Cohort',
      content: (
        <VStack alignItems="flex-start" gap="lg" w="full">
          <Field label="Name">
            <Input placeholder="e.g., Cerberus" />
          </Field>
          <Field label="Description">
            <Textarea placeholder="e.g., Cerberus is a design system..." />
          </Field>
        </VStack>
      ),
      actions: createCTAModalActions([
        {
          text: 'Create new',
          handleClick: () => alert('Create new'),
        },
        {
          text: 'Copy existing',
          handleClick: () => alert('Copy existing'),
        },
      ]),
    })
  }, [show])


  return (
    <HStack gap="4">
      <Button onClick={handleClick}>Update Cohorts</Button>
    </HStack>
  )
}
```
```tsx title="page.tsx"



function SomePage() {
  return(
    <CTAModal>
      <CTAFeature />
    </CTAModal>
  )
}
```


## Primitives

The CTAModal is an abstraction of the [Dialog primitives](./dialog) and does not provide any additional customization. To build your own CTAModal, use the `Dialog` components.

## API

The `CTAModal` component is an abstraction of the Dialog and accepts the same 
props as the `Dialog` component.

### Show Method Options

The `show` method accepts the following options:

| Name     | Default | Description                            |
| -------- | ------- | -------------------------------------- |
| heading | `''` | The heading of the modal. |
| description | `''` | The description of the modal. |
| icon | `undefined` | The icon to display in the modal. |
| actions | `[]` | The actions to display in the modal. **Requires the use of `createCTAModalActions` utility.** |

### Utilities

The `createCTAModalActions` utility accepts an array of objects with the following properties or ReactNodes:

## Action

| Name     | Default | Description                            |
| -------- | ------- | -------------------------------------- |
| text | `''` | The text of the action. |
| handleClick | `undefined` | The click handler of the action. |

## Link

Pass your Array of link components to the `createCTAModalActions` function.


---
## date-picker

---
title: Date Picker
description: A date picker component for selecting single or range dates.
npm: '@cerberus-design/react'
source: 'components/date-picker'
recipe: 'slots/datepicker.ts'
ark: 'date-picker'
---






```ts
import {
  DatePicker,
  DatePickerLabel,
  DatePickerInput,
  DatePickerCalendar
} from '@cerberus/react'
```

## Usage

The DatePicker component is a controlled component that allows users to select a single date or a range of dates. It consists of a label, input field, and a calendar view.

### Single Date Picker


```tsx
Example not found
```
}>
```tsx
import {
  DatePicker,
  DatePickerLabel,
  DatePickerInput,
  DatePickerCalendar,
  Field,
} from '@cerberus/react'


function StaticPreview() {
  return (
    <Box w="2/3">
      <Field>
        <DatePicker id="start_date" name="start_date">
          <DatePickerLabel>Start date</DatePickerLabel>
          <DatePickerInput />
          <DatePickerCalendar />
        </DatePicker>
      </Field>
    </Box>
  )
}
```


### Date Range Picker

To create a date range picker, set the `selectionMode` prop to `range` on the `DatePicker` component and use the `RangePickerInput` component as the input field.


```tsx
Example not found
```
}>
```tsx
import {
  DatePicker,
  DatePickerLabel,
  RangePickerInput,
  DatePickerCalendar,
  Field,
} from '@cerberus/react'


function RangePreview() {
  return (
    <Box gap="4" w="2/3">
      <Field>
        <DatePicker id="range_dates" name="range_dates" selectionMode="range">
          <DatePickerLabel>Search range</DatePickerLabel>
          <RangePickerInput />
          <DatePickerCalendar />
        </DatePicker>
      </Field>
    </Box>
  )
}
```


#### Using Default Values

You can set the default values for the range date picker by passing the `defaultValue` prop to the `DatePicker` component in the form of an Array of two date strings.

> **Note:** The `defaultValue` prop is only used when the component is first rendered. If you need to update the value dynamically, use the `value` prop instead.

}>
```tsx {18}
import {
  DatePicker,
  DatePickerLabel,
  RangePickerInput,
  DatePickerCalendar,
  Field,
  parseDate,
} from '@cerberus/react'


function RangeDefaultValuePreview() {
  const defaultValue = parseDate(['2025-01-01', '2025-01-15'])

  return (
    <Box gap="4" w="2/3">
      <Field>
        <DatePicker
          defaultValue={defaultValue}
          name="range_dates_dv"
          selectionMode="range"
        >
          <DatePickerLabel>Search range</DatePickerLabel>
          <RangePickerInput />
          <DatePickerCalendar />
        </DatePicker>
      </Field>
    </Box>
  )
}

```


### Custom Styles

You can customize the DatePicker width and other styles using the `css` prop along with the `data-part` selector to target specific primitives.

}>
```tsx
import {
  DatePicker,
  DatePickerLabel,
  DatePickerInput,
  DatePickerCalendar,
  Field,
} from '@cerberus/react'


function CustomStylesDemo() {
  return (
    <Grid columns={2} gap="4" w="3/4">
      <Field>
        <DatePicker
          name="custom_start_date"
          css={{
            w: 'full',
            '& :is([data-part=control])': {
              w: 'full',
            },
          }}
        >
          <DatePickerLabel>Start date</DatePickerLabel>
          <DatePickerInput />
          <DatePickerCalendar />
        </DatePicker>
      </Field>
      <Field>
        <DatePicker
          name="custom_end_date"
          css={{
            w: 'full',
            '& :is([data-part=control])': {
              w: 'full',
            },
          }}
        >
          <DatePickerLabel>End date</DatePickerLabel>
          <DatePickerInput />
          <DatePickerCalendar />
        </DatePicker>
      </Field>
    </Grid>
  )
}
```


## Date Helpers

The `DatePicker` component relies on different date utilities to handle date parsing and formatting. Here are the options available:

### Creating Dates

You can create a structured date Object using the `CalendarDate` class. This function accepts a date string or an object with year, month, and day properties.

```tsx

const date = new CalendarDate(2022, 2, 3);
```

<NoteAdmonition description={<>View the <a href="https://react-spectrum.adobe.com/internationalized/date/CalendarDate.html" target="_blank" rel="no-referrer">CalendarDate documentation</a> for more details on how to use it.</>} />

### Parsing Dates

You can use the `parseDate` function to convert an array of date strings into a date object that the `DatePicker` can understand.

```tsx

const date = parseDate(['2025-01-01', '2025-01-15'])
```

<NoteAdmonition description={<>View the <a href="https://react-spectrum.adobe.com/internationalized/date/CalendarDate.html#introduction" target="_blank" rel="no-referrer">parseDate documentation</a> for more details on how to use it.</>} />

### Today's Date
You can use the `today` function to get the current date in a format that the `DatePicker` can understand.

```tsx


const nyDate = today('America/New_York');
const localDate = today(getLocalTimeZone());
```

<NoteAdmonition description={<>View the <a href="https://react-spectrum.adobe.com/internationalized/date/CalendarDate.html" target="_blank" rel="no-referrer">today documentation</a> for more details on how to use it.</>} />

### Formatting Dates

You can use the `DateFormatter` class to format a date object into a string. This is useful for displaying dates in a human-readable format.

```tsx


const formatter = new DateFormatter('en-US', {
  dateStyle: 'long',
  timeZone: 'America/New_York'
})
const date = formatter.format(new Date()); // "January 1, 2025"
```
<NoteAdmonition description={<>View the <a href="https://react-spectrum.adobe.com/internationalized/date/DateFormatter.html" target="_blank" rel="no-referrer">DateFormatter documentation</a> for more details on how to use it.</>} />

## Primitives

You can utilize the primitive components or the `css` prop to customize the date picker.

| Component               | Description |
| ----------------------- | ----------- |
| DatePickerRoot               | The main container for the date-picker items. |
| DatePickerLabel          | The label for the date-picker. |
| DatePickerControl        | The control for the date-picker. |
| DatePickerInput          | The input field and trigger for the date-picker. |
| DatePickerTrigger        | The trigger for the date-picker. |
| DatePickerClearTrigger   | The trigger to clear the date-picker. |
| DatePickerPositioner     | The positioner for the date-picker. |
| DatePickerContent        | The content of the date-picker calendar. |
| DatePickerYearSelect     | The select input for the year in the date-picker. |
| DatePickerMonthSelect    | The select input for the month in the date-picker. |
| DatePickerView    | The container (view) of the calendar. |
| DatePickerContext        | The context provider for the date-picker calendar. |
| DatePickerViewControl  | The triggers that update the calendar in the view. |
| DatePickerPrevTrigger    | The trigger to navigate to the previous view. |
| DatePickerNextTrigger    | The trigger to navigate to the next view. |
| DatePickerViewTrigger    | The trigger to navigate to a specific view. |
| DatePickerRangeText      | The text that displays the range of dates selected. |
| DatePickerTable          | The table that contains the calendar. |
| DatePickerTableRow       | The row of the calendar table. |
| DatePickerTableHead      | The header of the calendar table. |
| DatePickerTableHeader    | The header cell of the calendar table. |
| DatePickerTableBody      | The body of the calendar table. |
| DatePickerTableCell      | The cell of the calendar table. |
| DatePickerTableTrigger    | The trigger of the cell in the calendar table. |

### Data Attributes

The Primitives additionally use the following data attributes for custom styling:

| Name     | Value | Description                            |
| -------- | ------| -------------------------------- |
| `data-scope` | `date-picker` | The scope of the components.       |
| `data-part` | `root` | The root container part. |
| `data-part` | `label` | The label part. |
| `data-part` | `control` | The control part. |
| `data-part` | `input` | The input part. |
| `data-part` | `trigger` | The trigger part. |
| `data-part` | `clearTrigger` | The clear trigger part. |
| `data-part` | `positioner` | The positioner part. |
| `data-part` | `content` | The content part. |
| `data-part` | `viewControl` | The view control part. |
| `data-part` | `prevTrigger` | The previous trigger part. |
| `data-part` | `nextTrigger` | The next trigger part. |
| `data-part` | `viewTrigger` | The view trigger part. |
| `data-part` | `rangeText` | The range text part. |
| `data-part` | `yearSelect` | The year select part. |
| `data-part` | `monthSelect` | The month select part. |
| `data-part` | `view` | The view part. |
| `data-part` | `table` | The table part. |
| `data-part` | `tableHead` | The table head part. |
| `data-part` | `tableBody` | The table body part. |
| `data-part` | `tableRow` | The table row part. |
| `data-part` | `tableHeader` | The table header part. |
| `data-part` | `tableCell` | The table cell part. |
| `data-part` | `tableCellTrigger` | The table cell trigger part. |

## API

### Props

#### DatePicker

The `DatePicker` component accepts all the props of the [`DatePickerRoot` primitive](https://ark-ui.com/react/docs/components/date-picker#api-reference)

#### DatePickerLabel

The `DatePickerLabel` component accepts all the props of the [`DatePickerLabel` primitive](https://ark-ui.com/react/docs/components/date-picker#api-reference)

#### DatePickerInput

The `DatePickerInput` component accepts all the props of the [`DatePickerInputEl` primitive](https://ark-ui.com/react/docs/components/date-picker#api-reference)

### Parts

The `DatePickerParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the DatePickerParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name     | Description                            |
| -------- | -------------------------------------- |
| Root           | The `DatePickerRoot` component and main container for the date-picker items. |
| Label          | The `DatePickerLabel` component and label for the date-picker. |
| Control        | The `DatePickerControl` component and control for the date-picker. |
| Input          | The `DatePickerInput` component and input field and trigger for the date-picker. |
| Trigger        | The `DatePickerRoot` component and trigger for the date-picker. |
| ClearTrigger   | The `DatePickerClearTrigger` component and trigger to clear the date-picker. |
| Positioner     | The `DatePickerPositioner` component and positioner for the date-picker. |
| Content        | The `DatePickerContent` component and content of the date-picker calendar. |
| YearSelect     | The `DatePickerYearSelect` component and select input for the year in the date-picker. |
| MonthSelect    | The `DatePickerMonthSelect` component and select input for the month in the date-picker. |
| View    | The `DatePickerView` component and container (view) of the calendar. |
| Context        | The `DatePickerContext` component and context provider for the date-picker calendar. |
| ViewControl  | The `DatePickerViewControl` component and triggers that update the calendar in the view. |
| PrevTrigger    | The `DatePickerPrevTrigger` component and trigger to navigate to the previous view. |
| NextTrigger    | The `DatePickerNextTrigger` component and trigger to navigate to the next view. |
| ViewTrigger    | The `DatePickerViewTrigger` component and trigger to navigate to a specific view. |
| RangeText      | The `DatePickerRangeText` component and text that displays the range of dates selected. |
| Table          | The `DatePickerTable` component and table that contains the calendar. |
| TableRow       | The `DatePickerTableRow` component and row of the calendar table. |
| TableHead      | The `DatePickerTableHead` component and header of the calendar table. |
| TableHeader    | The `DatePickerTableHeader` component and header cell of the calendar table. |
| TableBody      | The `DatePickerTableBody` component and body of the calendar table. |
| TableCell      | The `DatePickerTableCell` component and cell of the calendar table. |
| TableTrigger    | The `DatePickerTableTrigger` component and trigger of the cell in the calendar table. |


---
## dialog

---
title: Dialog
description: A modal window that appears on top of the main content.
npm: '@cerberus-design/react'
source: 'components/dialog'
recipe: 'slots/dialog.ts'
ark: 'dialog'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

To use the Dialog component, wrap it in a `DialogProvider` and use the `DialogTrigger` component to open the dialog. The `Dialog` component is a controlled component that can be used to display content in a modal.


```tsx
'use client'


import {
  Button,
  Dialog,
  DialogCloseIconTrigger,
  DialogCloseTrigger,
  DialogDescription,
  DialogHeading,
  DialogProvider,
  DialogTrigger,
} from '@cerberus-design/react'

export function BasicDemo() {
  return (
    <DialogProvider>
      <DialogTrigger asChild>
        <Button>open dialog</Button>
      </DialogTrigger>

      <Dialog size="auto">
        <DialogCloseIconTrigger />

        <Stack gap="xs" w="full">
          <DialogHeading>Dialog Title</DialogHeading>
          <DialogDescription maxW="prose">
            Far far away, behind the word mountains, far from the countries Vokalia and
            Consonantia, there live the blind texts. Separated they live in
            Bookmarksgrove right at the coast of the Semantics, a large language ocean.
          </DialogDescription>
        </Stack>

        <Box mt="md" w="full">
          <DialogCloseTrigger asChild>
            <Button>Close</Button>
          </DialogCloseTrigger>
        </Box>
      </Dialog>
    </DialogProvider>
  )
}
```


### Sizes

The Dialog component supports different sizes. You can set the size prop to `xs` to `lg`, or `full`.


```tsx
'use client'


import {
  Button,
  Dialog,
  DialogCloseIconTrigger,
  DialogCloseTrigger,
  DialogDescription,
  DialogHeading,
  DialogProps,
  DialogProvider,
  DialogTrigger,
} from '@cerberus-design/react'

export function SizesDemo() {
  return (
    <HStack gap="md">
      <DialogContent size="xs" />
      <DialogContent size="sm" />
      <DialogContent size="md" />
      <DialogContent size="lg" />
      <DialogContent size="full" />
      <DialogContent size="auto" />
    </HStack>
  )
}

function DialogContent(props: DialogProps) {
  return (
    <DialogProvider>
      <DialogTrigger asChild>
        <Button size="sm">open {String(props.size)}</Button>
      </DialogTrigger>

      <Dialog size={props.size}>
        <DialogCloseIconTrigger />

        <Stack gap="xs" w="full">
          <DialogHeading>Dialog Title</DialogHeading>
          <DialogDescription maxW="prose">
            Far far away, behind the word mountains, far from the countries Vokalia and
            Consonantia, there live the blind texts. Separated they live in
            Bookmarksgrove right at the coast of the Semantics, a large language ocean.
          </DialogDescription>
        </Stack>

        <Box mt="md" w="full">
          <DialogCloseTrigger asChild>
            <Button>Close</Button>
          </DialogCloseTrigger>
        </Box>
      </Dialog>
    </DialogProvider>
  )
}
```


### Controlled

Manage the dialog state using the `open` and `onOpenChange` props.

> **Note:** Notice how the dialog triggers automagically handle the state management via onOpenChange.


```tsx
'use client'


import {
  Button,
  Dialog,
  DialogCloseIconTrigger,
  DialogCloseTrigger,
  DialogDescription,
  DialogHeading,
  DialogProvider,
  DialogTrigger,
  type OpenChangeDetails,
} from '@cerberus-design/react'


export function ControlledDemo() {
  const [open, setOpen] = useSignal<boolean>(false)

  return (
    <DialogProvider
      open={open}
      onOpenChange={(details: OpenChangeDetails) => setOpen(details.open)}
    >
      <DialogTrigger asChild>
        <Button>open dialog</Button>
      </DialogTrigger>

      <Dialog size="auto">
        <DialogCloseIconTrigger />

        <Stack gap="xs" w="full">
          <DialogHeading>Dialog Title</DialogHeading>
          <DialogDescription maxW="prose">
            Far far away, behind the word mountains, far from the countries Vokalia and
            Consonantia, there live the blind texts. Separated they live in
            Bookmarksgrove right at the coast of the Semantics, a large language ocean.
          </DialogDescription>
        </Stack>

        <Box mt="md" w="full">
          <DialogCloseTrigger asChild>
            <Button>Close</Button>
          </DialogCloseTrigger>
        </Box>
      </Dialog>
    </DialogProvider>
  )
}
```


### Root Provider

An alternative way to control the dialog is to use the `RootProvider` component and the `useDialog` hook. This way you can access the state and methods from outside the component.


```tsx
'use client'


import {
  Button,
  Dialog,
  DialogCloseIconTrigger,
  DialogDescription,
  DialogHeading,
  DialogRootProvider,
  Text,
  useDialog,
} from '@cerberus-design/react'

export function RootProviderDemo() {
  const dialog = useDialog()

  return (
    <>
      <Button onClick={() => dialog.setOpen(true)}>
        Dialog is {dialog.open ? 'open' : 'closed'}
      </Button>

      <DialogRootProvider value={dialog}>
        <Dialog size="auto">
          <DialogCloseIconTrigger />
          <Stack gap="md" w="full">
            <DialogHeading asChild>
              <Text textStyle="heading-sm">Controlled Externally</Text>
            </DialogHeading>
            <DialogDescription maxW="prose">
              This dialog is controlled via the useDialog hook.
            </DialogDescription>
          </Stack>
        </Dialog>
      </DialogRootProvider>
    </>
  )
}
```


### Lazy Mount

Use `lazyMount` to render dialog content only when first opened. Combine with `unmountOnExit` to unmount when closed, freeing up resources.

Prefer this over conditionally rendering DialogProvider — see [Conditional Rendering](#conditional-rendering).


```tsx
'use client'


import {
  Button,
  Dialog,
  DialogCloseIconTrigger,
  DialogDescription,
  DialogHeading,
  DialogProvider,
  DialogTrigger,
  Text,
} from '@cerberus-design/react'

export function LazyDemo() {
  return (
    <DialogProvider lazyMount unmountOnExit>
      <DialogTrigger asChild>
        <Button>open dialog</Button>
      </DialogTrigger>

      <Dialog size="auto">
        <DialogCloseIconTrigger />

        <Stack gap="md" w="full">
          <DialogHeading asChild>
            <Text textStyle="heading-sm">Lazy Loaded</Text>
          </DialogHeading>
          <DialogDescription maxW="prose">
            This dialog content is only mounted when opened and unmounts on close.
          </DialogDescription>
        </Stack>
      </Dialog>
    </DialogProvider>
  )
}
```


### Inside Scroll

Make the content area scrollable while keeping header and footer fixed using `maxHeight` and `overflow: auto`.


```tsx
'use client'


import {
  Button,
  cerberus,
  Dialog,
  DialogCloseIconTrigger,
  DialogCloseTrigger,
  DialogHeading,
  DialogProvider,
  DialogTrigger,
  For,
} from '@cerberus-design/react'

export function InsideScrollDemo() {
  return (
    <DialogProvider>
      <DialogTrigger asChild>
        <Button>open dialog</Button>
      </DialogTrigger>

      <Dialog size="sm">
        <DialogCloseIconTrigger />

        <Stack gap="md" w="full">
          <DialogHeading>Dialog Title</DialogHeading>
          <Scrollable w="full" maxH="min(32rem, calc(100vh - 4rem))">
            <Stack gap="md" w="full">
              <For each={CONTENT_SECTIONS}>
                {(section) => (
                  <cerberus.section key={section.title} w="full">
                    <cerberus.h3 textStyle="heading-2xs">{section.title}</cerberus.h3>
                    <cerberus.small color="page.text.100" textStyle="body-sm">
                      {section.body}
                    </cerberus.small>
                  </cerberus.section>
                )}
              </For>
            </Stack>
          </Scrollable>
        </Stack>

        <Box mt="md" w="full">
          <DialogCloseTrigger asChild>
            <Button>Close</Button>
          </DialogCloseTrigger>
        </Box>
      </Dialog>
    </DialogProvider>
  )
}

const CONTENT_SECTIONS = [
  {
    title: '1. Acceptance of Terms',
    body: 'By accessing and using this service, you accept and agree to be bound by the terms and provisions of this agreement.',
  },
  {
    title: '2. Use License',
    body: 'Permission is granted to temporarily use this service for personal, non-commercial purposes only. This is the grant of a license, not a transfer of title.',
  },
  {
    title: '3. User Responsibilities',
    body: 'You are responsible for maintaining the confidentiality of your account and password. You agree to accept responsibility for all activities that occur under your account.',
  },
  {
    title: '4. Privacy Policy',
    body: 'Your use of this service is also governed by our Privacy Policy. Please review our Privacy Policy, which also governs the site and informs users of our data collection practices.',
  },
  {
    title: '5. Limitations',
    body: 'In no event shall we be liable for any damages arising out of the use or inability to use the materials on this service.',
  },
  {
    title: '6. Revisions',
    body: 'We may revise these terms of service at any time without notice. By using this service you are agreeing to be bound by the then current version of these terms.',
  },
  {
    title: '7. Governing Law',
    body: 'These terms and conditions are governed by and construed in accordance with applicable laws and you irrevocably submit to the exclusive jurisdiction of the courts.',
  },
]
```


### Outside Scroll

Make the positioner scrollable so the dialog can extend beyond the viewport.


```tsx
'use client'


import {
  Button,
  cerberus,
  DialogBackdrop,
  DialogCloseIconTrigger,
  DialogCloseTrigger,
  DialogContent,
  DialogHeading,
  DialogPositioner,
  DialogProvider,
  DialogTrigger,
  For,
  Portal,
} from '@cerberus-design/react'


export function OutsideScrollDemo() {
  const contentRef = useRef<HTMLDivElement | null>(null)

  return (
    <DialogProvider initialFocusEl={() => contentRef.current}>
      <DialogTrigger asChild>
        <Button>open dialog</Button>
      </DialogTrigger>

      <Portal>
        <DialogBackdrop />
        <DialogPositioner
          display="flex"
          alignItems="flex-start"
          justifyContent="center"
          position="fixed"
          inset="0"
          overflowY="auto"
          overscrollBehaviorY="contain"
          pointerEvents="auto"
        >
          <DialogContent
            ref={contentRef}
            margin="4rem auto"
            maxH="none"
            css={{
              '--dialog-content-w': '20rem',
            }}
          >
            <DialogCloseIconTrigger />

            <Stack gap="md" maxW="" w="full">
              <DialogHeading>Dialog Title</DialogHeading>
              <Stack gap="md" w="full">
                <For each={CONTENT_SECTIONS}>
                  {(section) => (
                    <cerberus.section key={section.title} w="full">
                      <cerberus.h3 textStyle="heading-2xs">{section.title}</cerberus.h3>
                      <cerberus.small color="page.text.100" textStyle="body-sm">
                        {section.body}
                      </cerberus.small>
                    </cerberus.section>
                  )}
                </For>
              </Stack>
            </Stack>

            <Box mt="md" w="full">
              <DialogCloseTrigger asChild>
                <Button>Close</Button>
              </DialogCloseTrigger>
            </Box>
          </DialogContent>
        </DialogPositioner>
      </Portal>
    </DialogProvider>
  )
}

const CONTENT_SECTIONS = [
  {
    title: '1. Acceptance of Terms',
    body: 'By accessing and using this service, you accept and agree to be bound by the terms and provisions of this agreement.',
  },
  {
    title: '2. Use License',
    body: 'Permission is granted to temporarily use this service for personal, non-commercial purposes only. This is the grant of a license, not a transfer of title.',
  },
  {
    title: '3. User Responsibilities',
    body: 'You are responsible for maintaining the confidentiality of your account and password. You agree to accept responsibility for all activities that occur under your account.',
  },
  {
    title: '4. Privacy Policy',
    body: 'Your use of this service is also governed by our Privacy Policy. Please review our Privacy Policy, which also governs the site and informs users of our data collection practices.',
  },
  {
    title: '5. Limitations',
    body: 'In no event shall we be liable for any damages arising out of the use or inability to use the materials on this service.',
  },
  {
    title: '6. Revisions',
    body: 'We may revise these terms of service at any time without notice. By using this service you are agreeing to be bound by the then current version of these terms.',
  },
  {
    title: '7. Governing Law',
    body: 'These terms and conditions are governed by and construed in accordance with applicable laws and you irrevocably submit to the exclusive jurisdiction of the courts.',
  },
]
```


### Initial Focus

Use `initialFocusEl` to control which element receives focus when the dialog opens.


```tsx
'use client'


import {
  Button,
  cerberus,
  Dialog,
  DialogCloseIconTrigger,
  DialogDescription,
  DialogHeading,
  DialogProvider,
  DialogTrigger,
  Field,
  Input,
} from '@cerberus-design/react'


export function InitialFocusDemo() {
  const inputRef = useRef<HTMLInputElement>(null)

  return (
    <DialogProvider initialFocusEl={() => inputRef.current}>
      <DialogTrigger asChild>
        <Button>open dialog</Button>
      </DialogTrigger>

      <Dialog size="auto">
        <DialogCloseIconTrigger />

        <Stack gap="md" w="full">
          <DialogHeading>Edit Profile</DialogHeading>
          <DialogDescription maxW="prose">
            The first input will be focused when the dialog opens.
          </DialogDescription>

          <cerberus.form mt="md" w="full">
            <Stack gap="md" w="full">
              <Field label="Name">
                <Input ref={inputRef} placeholder="Enter your name..." />
              </Field>
              <Field label="Emaiil">
                <Input placeholder="Enter your email..." type="email" />
              </Field>
            </Stack>
          </cerberus.form>
        </Stack>
      </Dialog>
    </DialogProvider>
  )
}
```


### Final Focus

Use `finalFocusEl` to control which element receives focus when the dialog closes. Defaults to the trigger element.


```tsx
'use client'


import {
  Button,
  Dialog,
  DialogCloseIconTrigger,
  DialogCloseTrigger,
  DialogDescription,
  DialogHeading,
  DialogProvider,
  DialogTrigger,
  Text,
} from '@cerberus-design/react'


export function FinalFocusDemo() {
  const finalRef = useRef<HTMLParagraphElement>(null)

  return (
    <VStack gap="md" w="full">
      <Text
        ref={finalRef}
        display="inline-block"
        _focusVisible={{
          boxShadow: 'none',
          outline: '3px solid',
          outlineColor: 'action.border.focus',
          outlineOffset: '2px',
        }}
      >
        I will receive focus when dialog closes
      </Text>

      <DialogProvider finalFocusEl={() => finalRef.current}>
        <DialogTrigger asChild>
          <Button>open dialog</Button>
        </DialogTrigger>

        <Dialog size="auto">
          <DialogCloseIconTrigger />

          <Stack gap="xs" w="full">
            <DialogHeading>Dialog Title</DialogHeading>
            <DialogDescription maxW="prose">
              Far far away, behind the word mountains, far from the countries Vokalia
              and Consonantia, there live the blind texts. Separated they live in
              Bookmarksgrove right at the coast of the Semantics, a large language
              ocean.
            </DialogDescription>
          </Stack>

          <Box mt="md" w="full">
            <DialogCloseTrigger asChild>
              <Button>Close</Button>
            </DialogCloseTrigger>
          </Box>
        </Dialog>
      </DialogProvider>
    </VStack>
  )
}
```


### Context

Access the dialog's state and methods with `DialogContext` or the `useDialogContext` hook.


```tsx
'use client'


import {
  Button,
  cerberus,
  Dialog,
  DialogCloseIconTrigger,
  DialogContext,
  DialogDescription,
  DialogHeading,
  DialogProvider,
  DialogTrigger,
} from '@cerberus-design/react'

export function ContextDemo() {
  return (
    <DialogProvider>
      <DialogTrigger asChild>
        <Button>open dialog</Button>
      </DialogTrigger>

      <Dialog size="auto">
        <DialogCloseIconTrigger />

        <Stack gap="xs" w="20rem">
          <DialogHeading>Status</DialogHeading>
          <DialogDescription maxW="prose">
            <DialogContext>
              {(dialog) => (
                <cerberus.p>Dialog is {dialog.open ? 'open' : 'closed'}</cerberus.p>
              )}
            </DialogContext>
          </DialogDescription>
        </Stack>
      </Dialog>
    </DialogProvider>
  )
}
```


### Open from Menu

Open a dialog imperatively from a `Menu` item using the `onClick` handler.


```tsx
'use client'



import {
  Button,
  Dialog,
  DialogCloseIconTrigger,
  DialogCloseTrigger,
  DialogDescription,
  DialogHeading,
  DialogProps,
  DialogProvider,
  Menu,
  MenuContent,
  MenuItem,
  MenuSeparator,
  MenuTrigger,
  OpenChangeDetails,
} from '@cerberus-design/react'


export function MenuDemo() {
  const [open, setOpen] = useSignal<boolean>(false)

  return (
    <>
      <Menu>
        <MenuTrigger>
          <Button>
            Actions
            <ChevronDown />
          </Button>
        </MenuTrigger>

        <MenuContent>
          <MenuItem value="edit">Edit</MenuItem>
          <MenuItem value="duplicate">Duplicate</MenuItem>
          <MenuSeparator />
          <MenuItem value="delete" onClick={() => setOpen(true)}>
            Delete
          </MenuItem>
        </MenuContent>
      </Menu>

      <MyDialog
        open={open}
        onOpenChange={(details: OpenChangeDetails) => setOpen(details.open)}
      />
    </>
  )
}

function MyDialog(props: DialogProps) {
  return (
    <DialogProvider {...props}>
      <Dialog size="auto">
        <DialogCloseIconTrigger />

        <Stack gap="xs" w="full">
          <DialogHeading>Dialog Title</DialogHeading>
          <DialogDescription maxW="prose">
            Far far away, behind the word mountains, far from the countries Vokalia and
            Consonantia, there live the blind texts. Separated they live in
            Bookmarksgrove right at the coast of the Semantics, a large language ocean.
          </DialogDescription>
        </Stack>

        <Box mt="md" w="full">
          <DialogCloseTrigger asChild>
            <Button>Close</Button>
          </DialogCloseTrigger>
        </Box>
      </Dialog>
    </DialogProvider>
  )
}
```


### Nested

Nest dialogs within one another. The parent receives `data-has-nested` and `--nested-layer-count` CSS variable for styling effects like zoom-out:


```tsx
// Source available in static configuration: {DEMOS.nestedCss}
```

<br />

```tsx
'use client'


import {
  Button,
  Dialog,
  DialogCloseIconTrigger,
  DialogDescription,
  DialogHeading,
  DialogRootProvider,
  DialogRootProviderProps,
  useDialog,
} from '@cerberus-design/react'

export function NestedDialog() {
  const parentDialog = useDialog()
  const childDialog = useDialog()

  return (
    <>
      <Button onClick={() => parentDialog.setOpen(true)}>Trigger</Button>
      <ParentDialog value={parentDialog} onClick={() => childDialog.setOpen(true)} />
      <ChildDialog value={childDialog} />
    </>
  )
}

interface ParentDialogProps extends DialogRootProviderProps {
  onClick?: () => void
}

function ParentDialog(props: ParentDialogProps) {
  return (
    <DialogRootProvider {...props}>
      <Dialog size="auto">
        <DialogCloseIconTrigger />

        <Stack gap="xs" w="full">
          <DialogHeading>Parent Dialog</DialogHeading>
          <DialogDescription maxW="prose">
            This is the parent dialog. Open a nested dialog to see automatic z-index
            management.
          </DialogDescription>
        </Stack>

        <Box mt="md" w="full">
          <Button onClick={props.onClick}>Open nested dialog</Button>
        </Box>
      </Dialog>
    </DialogRootProvider>
  )
}

function ChildDialog(props: DialogRootProviderProps) {
  return (
    <DialogRootProvider {...props}>
      <Dialog size="auto">
        <DialogCloseIconTrigger />

        <Stack gap="xs" w="full">
          <DialogHeading>Nested Dialog</DialogHeading>
          <DialogDescription maxW="prose">
            This dialog is nested within the parent with proper z-index layering.
          </DialogDescription>
        </Stack>
      </Dialog>
    </DialogRootProvider>
  )
}
```


### Confirmation

Intercept close attempts to show confirmation prompts, preventing data loss from unsaved changes.


```tsx
'use client'


import {
  Button,
  ButtonGroup,
  Dialog,
  DialogCloseIconTrigger,
  DialogDescription,
  DialogHeading,
  DialogRootProvider,
  DialogRootProviderProps,
  Field,
  Text,
  Textarea,
  useDialog,
} from '@cerberus-design/react'



export function ConfirmationDialog() {
  const [formContent, setFormContent] = useSignal<string>('')
  const [isParentDialogOpen, setIsParentDialogOpen] = useSignal<boolean>(false)

  const parentDialog = useDialog({
    open: isParentDialogOpen,
    onOpenChange: (details) => {
      if (!details.open && formContent.trim()) {
        confirmDialog.setOpen(true)
      } else {
        setIsParentDialogOpen(details.open)
      }
    },
  })
  const confirmDialog = useDialog()

  const handleConfirmClose = () => {
    confirmDialog.setOpen(false)
    parentDialog.setOpen(false)
    setFormContent('')
  }

  const handleCancel = () => {
    confirmDialog.setOpen(false)
  }

  return (
    <>
      <Button onClick={() => parentDialog.setOpen(true)}>Trigger</Button>
      <ParentDialog
        onChange={(e) => setFormContent(e.target.value)}
        formValue={formContent}
        value={parentDialog}
      />
      <ConfirmDialog
        value={confirmDialog}
        onCancel={handleCancel}
        onClose={handleConfirmClose}
      />
    </>
  )
}

interface ParentDialogProps extends DialogRootProviderProps {
  onChange?: ChangeEventHandler<HTMLTextAreaElement>
  formValue: string
}

function ParentDialog(props: ParentDialogProps) {
  return (
    <DialogRootProvider {...props}>
      <Dialog>
        <DialogCloseIconTrigger />

        <Stack gap="md" w="full">
          <DialogHeading asChild>
            <Text textStyle="heading-sm">Edit Content</Text>
          </DialogHeading>
          <DialogDescription maxW="prose">
            Make changes to your content. You&apos;ll be asked to confirm before closing
            if there are unsaved changes.
          </DialogDescription>

          <Field>
            <Textarea
              value={props.formValue}
              onChange={props.onChange}
              placeholder="Enter some text..."
              rows={4}
            />
          </Field>
        </Stack>
      </Dialog>
    </DialogRootProvider>
  )
}

interface ConfirmationDialogProps extends DialogRootProviderProps {
  onCancel?: () => void
  onClose?: () => void
}

function ConfirmDialog(props: ConfirmationDialogProps) {
  return (
    <DialogRootProvider {...props}>
      <Dialog size="auto">
        <DialogCloseIconTrigger />

        <Stack gap="md" w="full">
          <DialogHeading asChild>
            <Text textStyle="heading-sm">Unsaved Changes</Text>
          </DialogHeading>
          <DialogDescription maxW="prose">
            You have unsaved changes. Are you sure you want to close without saving?
          </DialogDescription>

          <ButtonGroup>
            <Button onClick={props.onCancel} usage="outlined-subtle">
              Keep Editing
            </Button>
            <Button palette="danger" onClick={props.onClose}>
              Discard Changes
            </Button>
          </ButtonGroup>
        </Stack>
      </Dialog>
    </DialogRootProvider>
  )
}
```


### Non-Modal

We don't recommend using a non-modal dialog due to the accessibility concerns they present. In event you need it, here's what you can do:

- set the `modal` prop to `false`
- set `pointerEvents` to `none` on the `Dialog.Positioner` component
- (optional) set the `closeOnInteractOutside` prop to `false`
  Preview


```tsx
'use client'


import {
  Button,
  DialogCloseIconTrigger,
  DialogCloseTrigger,
  DialogContent,
  DialogDescription,
  DialogHeading,
  DialogPositioner,
  DialogProvider,
  DialogTrigger,
  Portal,
} from '@cerberus-design/react'

export function NonModalDemo() {
  return (
    <DialogProvider closeOnInteractOutside={false} modal={false}>
      <DialogTrigger asChild>
        <Button>open dialog</Button>
      </DialogTrigger>

      <Portal>
        <DialogPositioner pointerEvents="none">
          <DialogContent size="auto">
            <DialogCloseIconTrigger />

            <Stack gap="xs" w="full">
              <DialogHeading>Dialog Title</DialogHeading>
              <DialogDescription maxW="prose">
                Far far away, behind the word mountains, far from the countries Vokalia
                and Consonantia, there live the blind texts. Separated they live in
                Bookmarksgrove right at the coast of the Semantics, a large language
                ocean.
              </DialogDescription>
            </Stack>

            <Box mt="md" w="full">
              <DialogCloseTrigger asChild>
                <Button>Close</Button>
              </DialogCloseTrigger>
            </Box>
          </DialogContent>
        </DialogPositioner>
      </Portal>
    </DialogProvider>
  )
}
```


## Guides

### Close Behavior

- `closeOnEscape={false}` - Prevent closing on Escape
- `closeOnInteractOutside={false}` - Prevent closing on outside click

For conditional control, use `onEscapeKeyDown` or `onInteractOutside` with `e.preventDefault()`.

### Conditional Rendering

Unmounting `Dialog.Root` when toggling open state can break focus, scroll lock, and cleanup. Keep the root mounted and control it with `open` / `onOpenChange`.

When you want portal content out of the DOM while closed, add `lazyMount` and `unmountOnExit` to the root.


```tsx



// ❌ Avoid
export function Dont() {
  const [isOpen, setOpen] = useSignal<boolean>(false)

  if (isOpen) {
    return (
      <DialogRoot
        open={isOpen}
        onOpenChange={(e: OpenChangeDetails) => setOpen(e.open)}
      >
        <Portal>...</Portal>
      </DialogRoot>
    )
  }

  return null
}

// ✅ Prefer
export function Do() {
  const [isOpen, setOpen] = useSignal<boolean>(false)
  return (
    <DialogRoot
      open={isOpen}
      onOpenChange={(e: OpenChangeDetails) => setOpen(e.open)}
      lazyMount
      unmountOnExit
    >
      <Portal>...</Portal>
    </DialogRoot>
  )
}
```


### Z-index Stacking

Use the `--layer-index` CSS variable for z-index management of stacked dialogs:


```tsx
// Source available in static configuration: {DEMOS.zIndexCss}
```


### Dynamic Imports

When using `lazyMount` with `lazy` or Next.js `dynamic`, wrap the imported component in `Suspense`:


```tsx




const HeavyComponent = dynamic(() => import('./heavy'))

export function DynamicDemo() {
  return (
    <DialogProvider lazyMount>
      <DialogTrigger>Open</DialogTrigger>
      <Dialog>
        <Suspense fallback={<div>Loading...</div>}>
          <HeavyComponent />
        </Suspense>
      </Dialog>
    </DialogProvider>
  )
}
```


### Customizing

You can customize the `Dialog` using style props and data selectors on any slot primitve.

## Primitives

You can utilize the primitive components or the `css` prop to customize the dialog.

| Component              | Description                                                  |
| ---------------------- | ------------------------------------------------------------ |
| DialogProvider         | The main state context for the dialog.                       |
| DialogTrigger          | The trigger element that opens the dialog.                   |
| DialogBackdrop         | The backdrop that covers the page when the dialog is open.   |
| DialogPositioner       | The container that positions the dialog content.             |
| DialogContent          | The content that is shown within the dialog.                 |
| DialogHeading          | The heading title of the dialog.                             |
| DialogDescription      | The description of the dialog.                               |
| DialogCloseTrigger     | The trigger element that closes the dialog.                  |
| DialogCloseIconTrigger | The trigger element that closes the dialog with an "x" icon. |

## API

### Props

The `Dialog` component is an abstraction of the primitives and accepts the following props:

#### Root Props:

| Prop                     | Type                                       | Required | Description                                                                                                           |
| ------------------------ | ------------------------------------------ | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `aria-label`             | `string`                                   | No       | Human readable label for the dialog, in event the dialog title is not rendered                                        |
| `closeOnEscape`          | `boolean`                                  | No       | Whether to close the dialog when the escape key is pressed                                                            |
| `closeOnInteractOutside` | `boolean`                                  | No       | Whether to close the dialog when the outside is clicked                                                               |
| `defaultOpen`            | `boolean`                                  | No       | The initial open state of the dialog when rendered. Use when you don't need to control the open state of the dialog.  |
| `finalFocusEl`           | `() => MaybeElement`                       | No       | Element to receive focus when the dialog is closed                                                                    |
| `id`                     | `string`                                   | No       | The unique identifier of the machine.                                                                                 |
| `ids`                    | `Partial<PrimitiveLayers>`                 | No       | The ids of the elements in the dialog. Useful for composition.                                                        |
| `immediate`              | `boolean`                                  | No       | Whether to synchronize the present change immediately or defer it to the next frame                                   |
| `initialFocusEl`         | `() => MaybeElement`                       | No       | Element to receive focus when the dialog is opened                                                                    |
| `lazyMount`              | `boolean`                                  | No       | Whether to enable lazy mounting                                                                                       |
| `modal`                  | `boolean`                                  | No       | Whether to prevent pointer interaction outside the element and hide all content below it                              |
| `onEscapeKeyDown`        | `(event: KeyboardEvent) => void`           | No       | Function called when the escape key is pressed                                                                        |
| `onExitComplete`         | `VoidFunction`                             | No       | Function called when the animation ends in the closed state                                                           |
| `onFocusOutside`         | `(event: FocusOutsideEvent) => void`       | No       | Function called when the focus is moved outside the component                                                         |
| `onInteractOutside`      | `(event: InteractOutsideEvent) => void`    | No       | Function called when an interaction happens outside the component                                                     |
| `onOpenChange`           | `(details: OpenChangeDetails) => void`     | No       | Function to call when the dialog's open state changes                                                                 |
| `onPointerDownOutside`   | `(event: PointerDownOutsideEvent) => void` | No       | Function called when the pointer is pressed down outside the component                                                |
| `onRequestDismiss`       | `(event: LayerDismissEvent) => void`       | No       | Function called when this layer is closed due to a parent layer being closed                                          |
| `open`                   | `boolean`                                  | No       | The controlled open state of the dialog                                                                               |
| `persistentElements`     | `(() => Element \| null)[]`                | No       | Returns the persistent elements that: should not have pointer-events disabled or should not trigger the dismiss event |
| `present`                | `boolean`                                  | No       | Whether the node is present (controlled by the user)                                                                  |
| `preventScroll`          | `boolean`                                  | No       | Whether to prevent scrolling behind the dialog when it's opened                                                       |
| `restoreFocus`           | `boolean`                                  | No       | Whether to restore focus to the element that had focus before the dialog was opened                                   |
| `role`                   | `'dialog' \| 'alertdialog'`                | No       | The dialog's role                                                                                                     |
| `skipAnimationOnMount`   | `boolean`                                  | No       | Whether to allow the initial presence animation.                                                                      |
| `size`                   | string                                     | No       | This size of the Dialog.                                                                                              |
| `trapFocus`              | `boolean`                                  | No       | Whether to trap focus inside the dialog when it's opened                                                              |
| `unmountOnExit`          | `boolean`                                  | No       | Whether to unmount on exit.                                                                                           |

#### Backdrop Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Backdrop Data Attributes:

| Attribute      | Value              |
| -------------- | ------------------ |
| `[data-scope]` | dialog             |
| `[data-part]`  | backdrop           |
| `[data-state]` | "open" \| "closed" |

#### Backdrop CSS Variables:

| Variable        | Description                                     |
| --------------- | ----------------------------------------------- |
| `--layer-index` | The index of the dismissable in the layer stack |

#### CloseTrigger Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Content Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Content Data Attributes:

| Attribute           | Value              |
| ------------------- | ------------------ |
| `[data-scope]`      | dialog             |
| `[data-part]`       | content            |
| `[data-state]`      | "open" \| "closed" |
| `[data-nested]`     | dialog             |
| `[data-has-nested]` | dialog             |

#### Content CSS Variables:

| Variable               | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `--layer-index`        | The index of the dismissable in the layer stack |
| `--nested-layer-count` | The number of nested dialogs                    |

#### Description Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Positioner Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### RootProvider Props

| Prop                   | Type              | Required | Description                                                                                         |
| ---------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------- |
| `value`                | `UseDialogReturn` | Yes      |                                                                                                     |
| `asChild`              | `boolean`         | No       | Use the provided child element as the default rendered element, combining their props and behavior. |
| `immediate`            | `boolean`         | No       | Whether to synchronize the present change immediately or defer it to the next frame                 |
| `lazyMount`            | `boolean`         | No       | Whether to enable lazy mounting                                                                     |
| `onExitComplete`       | `VoidFunction`    | No       | Function called when the animation ends in the closed state                                         |
| `present`              | `boolean`         | No       | Whether the node is present (controlled by the user)                                                |
| `skipAnimationOnMount` | `boolean`         | No       | Whether to allow the initial presence animation.                                                    |
| `unmountOnExit`        | `boolean`         | No       | Whether to unmount on exit.                                                                         |

#### Title Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Trigger Props

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Trigger Data Attributes

| Attribute        | Value                 |
| ---------------- | --------------------- |
| `[data-scope]`   | dialog                |
| `[data-part]`    | trigger               |
| `[data-value]`   | The value of the item |
| `[data-state]`   | "open" \| "closed"    |
| `[data-current]` | Present when current  |


---
## divider

---
title: Divider
description: Used to create visual separation between content.
panda: https://panda-css.com/docs/concepts/patterns#divider
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

Used to visually separate content.


```tsx



export function BasicDemo() {
  return (
    <VStack w="3/4">
      <Text>First</Text>
      <Divider color="page.border.initial" />
      <Text>Second</Text>
      <Divider color="page.border.initial" />
      <Text>Third</Text>
    </VStack>
  )
}
```


## Appearance

To change the appearance of the divider, use the `borderStyle` prop.


```tsx


export function AppearanceDemo() {
  return (
    <VStack gap="lg" w="3/4">
      <Divider borderStyle="solid" />
      <Divider borderStyle="dashed" />
      <Divider borderStyle="dotted" />
    </VStack>
  )
}
```


### Orientation

Use the `orientation` prop to change the orientation of the divider.


```tsx




function VertDivider(props: PropsWithChildren<object>) {
  return (
    <Divider color="page.border.initial" orientation="vertical" {...props} />
  )
}

export function OrientationDemo() {
  return (
    <HStack h="2rem" gap="lg" justify="center" pt="md" w="3/4">
      <Text>Text</Text>
      <VertDivider />
      <Text>Text</Text>
      <VertDivider />
      <Text>Text</Text>
    </HStack>
  )
}
```


### Thickness

Use the `thickness` prop to change the thickness of the divider.


```tsx


export function ThicknessDemo() {
  return (
    <VStack gap="lg" w="3/4">
      <Divider thickness="1px" />
      <Divider thickness="2px" />
      <Divider thickness="4px" />
    </VStack>
  )
}
```


### Color

Use the `color` prop to change the color of the divider.


```tsx


export function ColorDemo() {
  return (
    <VStack gap="lg" w="3/4">
      <Divider color="page.border.initial" />
      <Divider color="info.border.initial" />
      <Divider color="neutral.100" />
    </VStack>
  )
}
```


## Label

Create visual labels by combining a `Divider` with other layout components.


```tsx




function TextLabel(props: PropsWithChildren<object>) {
  return <Text flexShrink="0" textStyle="label-sm" {...props} />
}

export function LabelDemo() {
  return (
    <Stack w="3/4">
      <HStack>
        <TextLabel>Label (start)</TextLabel>
        <Divider flex="1" />
      </HStack>

      <HStack>
        <Divider flex="1" />
        <TextLabel>Label (end)</TextLabel>
      </HStack>

      <HStack>
        <Divider flex="1" />
        <TextLabel>Label (center)</TextLabel>
        <Divider flex="1" />
      </HStack>
    </Stack>
  )
}
```


## Props

The `Divider` accepts any style prop in addition to the following:

| Prop         | Type        | Description                                     |
|--------------|-------------|-------------------------------------------------|
| `orientation` | `horizontal,vertical` | The orientation of the divider. Defaults to `"horizontal"`. |
| `thickness`   | `string`    | The thickness of the divider. Defaults to `"1px"`. |
| `color`       | `string`    | The color of the divider. Defaults to `"gray.200"`. |


---
## download-trigger

---
title: 'Download Trigger'
description: 'Programmatically trigger file downloads'
npm: '@cerberus-design/react'
arkUtility: 'download-trigger'
---




## Motivation

The `DownloadTrigger` component provides a convenient way to programmatically trigger file downloads in web
applications. It handles the complexities of downloading files, whether they are URLs, Blobs, or other data types.

## Examples

### Basic

Pass the data you want to download to the `data` prop, and specify the `fileName` and `mimeType` of the file.

} />
```tsx


export const Basic = () => {
  return (
    <Button asChild>
      <DownloadTrigger
        data="Hello world"
        fileName="hello.txt"
        mimeType="text/plain"
      >
        Download txt
      </DownloadTrigger>
    </Button>
  )
}
```

### Download SVG

Here's an example of how to download an SVG file.

```tsx


export const Svg = () => {
  return (
    <DownloadTrigger
      data='<svg xmlns="http://www.w3.org/2000/svg" width="100" height="100"><circle cx="50" cy="50" r="40" stroke="black" stroke-width="3" fill="red"/></svg>'
      fileName="circle.svg"
      mimeType="image/svg+xml"
    >
      Download SVG
    </DownloadTrigger>
  )
}
```

### Promise

You can also trigger downloads from a promise that returns a `Blob`, `File`, or `string`.

```tsx


export const WithPromise = () => {
  const fetchImage = async () => {
    const response = await fetch('https://picsum.photos/200/300')
    return response.blob()
  }

  return (
    <DownloadTrigger data={fetchImage} fileName="random-image.jpg" mimeType="image/jpeg">
      Download Image
    </DownloadTrigger>
  )
}
```


## API Reference

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `data` | `DownloadableData` |   Yes | The data to download |
| `fileName` | `string` | Yes | The name of the file to download |
| `mimeType` | `FileMimeType` | Yes | The MIME type of the data to download |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


---
## environment

---
title: 'Environment'
description: 'Set up components for custom environments like iframes, Shadow DOM, or Electron.'
npm: '@cerberus-design/react'
arkUtility: 'environment'
---

## Motivation

We use [Zag.js](https://zagjs.com/overview/composition#custom-window-environment) internally, which relies on DOM query
methods like `document.querySelectorAll` and `document.getElementById`. In custom environments like iframes, Shadow DOM,
or Electron, these methods might not work as expected.

To handle this, Ark UI includes the `EnvironmentProvider`, allowing you to set the appropriate root node or document,
ensuring correct DOM queries.

## Setup

To support custom environments like an iframe, Shadow DOM or Electron, render the `EnvironmentProvider` component to
provide the environment context to all Ark UI components.

```tsx



export const App = () => {
  return (
    <Frame title="IFrame Context">
      <EnvironmentProvider>{/* Your App */}</EnvironmentProvider>
    </Frame>
  )
}

```


### Usage in iframe

The `EnvironmentProvider` component will automatically detect the current environment and set the correct environment
context. However, you can also manually set the `Document` like shown in this example below:

```jsx



export const App = () => (
  <Frame title="IFrame Context">
    <FrameContextConsumer>
      {({ document }) => <EnvironmentProvider value={document}>{/* Your App */}</EnvironmentProvider>}
    </FrameContextConsumer>
  </Frame>
)
```

## Context

Use the `useEnvironmentContext` hook to access the `RootNode`, `Document`, and `Window`.

```tsx


export const Usage = () => {
  const { getRootNode } = useEnvironmentContext()

  return <pre>{JSON.stringify(getRootNode(), null, 2)}</pre>
}

```


## API Reference

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `RootNode` |  No |  |


---
## feature-flags

---
title: 'Feature Flags'
description: 'Feature Flags display or hide content in the UI.'
npm: '@cerberus-design/react'
source: 'components/feature-flag'
---

import {
  WhenToUseAdmonition
} from '@/app/components/Admonition'



```ts

```

> **Note:** When you need render a component based on if it should be enabled or not.

## Usage

}>
```tsx title="nav.tsx" {16-19}
'use client'




function FeatureFlagsPreview() {
  const flags = useMemo(
    () => ({
      featureOne: true,
      featureTwo: false,
    }),
    [],
  )

  return (
    <FeatureFlags flags={flags}>
      <FeatureFlag flag="featureOne">This is a visible feature</FeatureFlag>
      <FeatureFlag flag="featureTwo">This is a hidden feature</FeatureFlag>
    </FeatureFlags>
  )
}
```


## API

```ts showLineNumbers=false
export interface FeatureFlagsProviderValue {
  flags: Record<string, boolean>
}

export interface FeatureFlagProps {
  // A unique key of the flags data passed into the provider.
  flag: string
}

define function FeatureFlag(props: PropsWithChildren<FeatureFlagProps>): JSX.Element
```

### Props

The `FeatureFlag` component accepts the following props:

| Name     | Default | Description                                                   |
| -------- | ------- | ------------------------------------------------------------- |
| flag | null    | A unique key of the flags data passed into the provider.            |


---
## field

---
title: Field
description: The Field component is used to manage form fields, providing a consistent way to display labels, helper texts, and error messages.
npm: '@cerberus-design/react'
source: 'components/field'
recipe: 'slots/field.ts'
ark: 'field'
---






```ts
import {
  Field,
  FieldParts,
} from '@cerberus/react'
```

## Usage

The `Field` component helps manage the state of form fields and ensures consistent display of labels, helper texts, and error messages.

}>
```tsx title="some-form.tsx"



export function BasicFieldPreview() {
  return (
    <form action={someAction} method="post">
      <Box w="1/2">
        <VStack alignItems="flex-start" gap="lg" w="full">
          <Field
            ids={{
              control: 'email',
            }}
            label="Enter your email"
            helperText="We'll never share your email with anyone else."
            required
          >
            <Input name="email" type="email" />
          </Field>
          <Field
            ids={{
              control: 'invalid-name',
            }}
            label="Invalid example"
            helperText="This is an example of an invalid field."
            errorText="A name is required to submit this form. It replaces the helper text."
            invalid
            required
          >
            <Input name="invalid-name" type="text" />
          </Field>
          <Field
            ids={{
              control: 'message',
            }}
            label="Anything else you want to tell us?"
            helperText="This will help us learn more about you."
            secondaryHelperText="0/300"
          >
            <Textarea name="message" />
          </Field>
        </VStack>
      </Box>
    </form>
  )
}
```


## Hidden Labels

For accessibility compliance, use the `hideLabel` prop to visually hide labels while keeping them accessible to screen readers. This is useful for search inputs and other cases where the visual label would be redundant.

}>
```tsx title="hidden-label-fields.tsx"



export function HiddenLabelFields() {
  return (
    <Box w="1/2">
      <VStack alignItems="flex-start" gap="lg" w="full">
        <Field
          label="Search something"
          helperText="Label is hidden but accessible to screen readers"
          hideLabel
        >
          <Input name="search" type="search" placeholder="Type to search..." />
        </Field>
        <Field
          label="Global search"
          hideLabel
          required
        >
          <Input name="global-search" type="search" placeholder="Search the entire site..." />
        </Field>
      </VStack>
    </Box>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the field.

| Component | Description |
| --------- | ----------- |
| FieldRoot    | The context provider for the Field parts |
| FieldLabel   | The label of the field |
| FieldInput   | The input of the field |
| FieldTextarea   | The textarea of the field |
| FieldHelperText | The helper text of the field |
| FieldErrorText  | The error text of the field |
| StartIndicator  | The start indicator of the field |
| StatusIndicator | The status indicator or end icon of the field |
| RequiredIndicator | The required indicator of the field |

}>
```tsx



export function CustomField() {
  return (
    <Box w="1/2">
      <FieldParts.Root ids={{ control: 'customField' }}>
        <FieldParts.Label
          css={{
            fontSize: 'xl',
            fontWeight: 'black',
            textTransform: 'uppercase',
          }}
        >
          Custom Label
        </FieldParts.Label>
        <FieldParts.Input
          css={{
            transform: 'skewX(-10deg)',
          }}
          type="text"
        />
        <FieldParts.HelperText
          css={{
            fontStyle: 'italic',
          }}
        >
          Custom Helper Text
        </FieldParts.HelperText>
      </FieldParts.Root>
    </Box>
  )
}
```



## API

### Props

The `Field` component is an abstraction of the primitives and accepts the following props:

| Name     | Default | Description                                            |
| -------- | ------- | ------------------------------------------------------ |
| label    |         | The label to show above the field input. |
| helperText |         | The helper text to show below the field input. |
| secondaryHelperText |         | The secondary helper text to show below the field input at the end of the row. |
| errorText  |         | The error text to show below the field input. It replaces the helperText when visible. |
| hideLabel | `false` | Whether to hide the label visually while keeping it accessible to screen readers. |


The `Field` component also accepts all the props of the [`FieldRoot` primitive props](https://ark-ui.com/react/docs/components/field#api-reference)

### Parts

The `FieldParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the FieldParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name     | Description                            |
| -------- | -------------------------------------- |
| Root     | The `FieldRoot` component which is the Provider for the family. |
| Label     | The `FieldLabel` component which displays the label and "required" notice. |
| Input     | The `FieldInput` component which is the input field. |
| Textarea  | The `FieldTextarea` component which is the textarea field. |
| HelperText | The `FieldHelperText` component which displays the helper text. |
| ErrorText  | The `FieldErrorText` component which displays the error text. |
| StartIndicator | The `StartIndicator` component which displays an indicator of your choice at the start of the field. |
| StatusIndicator | The `StatusIndicator` component which displays an indicator of your choice at the end of the field. |
| RequiredIndicator | The `RequiredIndicator` component which displays an indicator of your choice when the field is marked `required`. |


---
## fieldset

---
title: Fieldset
description: The Fieldset component groups form fields together with a shared legend and helper/error text.
npm: '@cerberus-design/react'
source: 'components/fieldset'
recipe: 'slots/fieldset.ts'
ark: 'fieldset'
---






```ts

```

## Usage

### Form Section Example

The `Fieldset` component can be used to group related form elements together using the `usage` prop which can be either `formSection` or `fieldGroup` (default).

}>
```tsx title="radio-group.tsx" {18}
import {
  Fieldset,
  Field,
  Input,
  RadioGroup,
  Radio,
} from '@cerberus/react'


export function BasicDemo() {
  return (
    <Box w="1/2">
      <Fieldset
        invalid
        legend="Update your profile"
        helperText="You can update your profile information here."
        errorText="This is an error message for the fieldset group."
        usage="formSection"
      >
        <VStack alignItems="flex-start" gap="lg" paddingBlock="lg" w="full">
          <Field
            ids={{
              control: 'first_name',
            }}
            label="What is your first name?"
            required
          >
            <Input name="first_name" />
          </Field>

          <Field
            ids={{
              control: 'display_name',
            }}
            label="What is your display name?"
            required
          >
            <Input name="last_name" />
          </Field>
        </VStack>
      </Fieldset>
    </Box>
  )
}
```


### Field Group Example

When use need to label a group of Radio or Checkbox inputs, use the `usage` prop with the value `fieldGroup`.

}>
```tsx title="radio-group.tsx" {18}
import {
  Fieldset,
  RadioGroup,
  Radio,
} from '@cerberus/react'


function FieldsetGroupDemo() {
  return (
    <Box w="1/2">
      <Fieldset legend="Who is your favorite?">
        <RadioGroup name="favorite" defaultValue="cerberus">
          <Radio value="cerberus">Cerberus</Radio>
          <Radio value="hades">Hades</Radio>
          <Radio value="zeus">Zeus</Radio>
        </RadioGroup>
      </Fieldset>
    </Box>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the Fieldset.

| Component | Description |
| --------- | ----------- |
| FieldsetRoot    | The context provider for the Fieldset parts |
| FieldsetLegend  | The label of the fieldset |
| FieldsetHelperText   | The label description for the Fieldset |
| FieldsetErrorText   | The error message for the Fieldset |

}>
```tsx title="custom fieldset"



function CustomDemo() {
  return (
    <Box w="1/2">
      <FieldsetParts.Root invalid>
        <FieldsetParts.Legend
          css={{
            textStyle: 'heading-lg',
          }}
        >
          Custom Legend
        </FieldsetParts.Legend>
        <FieldsetParts.HelperText
          css={{
            color: 'page.text.200',
            fontStyle: 'italic',
            textStyle: 'body-sm',
          }}
        >
          This is some custom Helper Text
        </FieldsetParts.HelperText>

        <Box paddingBlock="lg" w="full">
          <Field label="This is a custom example">
            <Input />
          </Field>
        </Box>

        <FieldsetParts.ErrorText
          css={{
            bgColor: 'danger.bg.initial',
            color: 'danger.text.100',
            p: 4,
            rounded: 'lg',
          }}
        >
          This is a custom Error Text
        </FieldsetParts.ErrorText>
      </FieldsetParts.Root>
    </Box>
  )
}
```


## API

### Props

The `Fieldset` component is an abstraction of the primitives and accepts the following props:

| Name     | Default | Description                                            |
| -------- | ------- | ------------------------------------------------------ |
| usage     |  `fieldGroup`   | The type of fieldset to display.              |


The `Fieldset` component also accepts all the props of the [`FieldsetRoot` primitive props](https://ark-ui.com/react/docs/components/fieldset#api-reference)

### Parts

The `FieldsetParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the FieldsetParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name     | Description                            |
| -------- | -------------------------------------- |
| Root     | The `FieldsetRoot` component which is the Provider for the family. |
| Legend     | The `FieldsetLegend` component which displays the label. |
| HelperText     | The `FieldsetHelperText` component which displays the description text. |
| ErrorText     | The `FieldsetErrorText` component which displays the error text when the group is marked `invalid`. |


---
## file-uploader

---
title: File Uploader
description: A component to allow users to upload files and display their status.
npm: '@cerberus-design/react'
source: 'components/file-upload'
recipe: 'slots/fileUploader.ts'
ark: 'file-upload'
---





```ts

```

## Uploading Files

To allow users to upload files, use the `FileUploader` component. This will provide
a drag-and-drop area for users to upload files which is also clickable.

Once a valid file is added, a preview card of the file will be displayed.

}>
```tsx title="img-uploader.tsx"


export function BasicFileUploader() {
  return (
    <FileUploader
      accept="image/*"
      heading="Upload Files"
      name="basic-example"
    />
  )
}
```


## File Status

If you choose to process the file, you can use the `FileStatus` component to display the status of the job.

}>
```tsx title="file-status.tsx"
'use client'

import {
  FileStatus,
  type FileStatusActions,
  processStatus,
} from '@cerberus/react'



export function UploadingCardsPreview() {
  const handleClick = useCallback(
    (status: FileStatusActions, e: MouseEvent<HTMLButtonElement>) =>
      console.log(status, e),
    [],
  )

  return (
    <div
      className={vstack({
        maxW: '36rem',
        w: '3/4',
      })}
    >
      <FileStatus
        id="todo"
        file="file.txt"
        now={0}
        onClick={handleClick}
        status={processStatus.TODO}
      />
      <FileStatus
        id="processing"
        file="file.txt"
        now={50}
        onClick={handleClick}
        status={processStatus.PROCESSING}
      />
      <FileStatus
        id="done"
        file="file.txt"
        now={100}
        onClick={handleClick}
        status={processStatus.DONE}
      />
      <FileStatus
        id="error"
        file="file.txt"
        now={0}
        onClick={handleClick}
        status={processStatus.ERROR}
      />
    </div>
  )
}
```


## Accepted File Types

Use the `accept` prop to restrict the file types that can be uploaded. This prop accepts MIME types (e.g., `image/png`,
`image/jpeg`) or file extensions (e.g., `.pdf`, `.txt`).

When users attempt to upload files that don't match the accepted types, these files will be automatically rejected and
appear in the `rejectedFiles` array with a `FILE_INVALID_TYPE` error code.

```typescript


<FileUploader
  id="file-uploader"
  accept="image/png, image/jpeg"
/>
```

## Error Handling

The `FileUploader` component provides comprehensive validation and error handling 
capabilities. You can set various constraints and handle different types of 
validation errors:

**Built-in Validation Props:**

- `maxFiles` - Maximum number of files allowed
- `maxFileSize` - Maximum file size in bytes
- `minFileSize` - Minimum file size in bytes
- `accept` - Allowed MIME types or file extensions

**Built-in Error Types:**

- `TOO_MANY_FILES` - Exceeds maxFiles limit
- `FILE_INVALID_TYPE` - File type not in accept list
- `FILE_TOO_LARGE` - File size exceeds maxFileSize
- `FILE_TOO_SMALL` - File size below minFileSize
- `FILE_INVALID` - Generic validation failure
- `FILE_EXISTS` - Duplicate file detected


```tsx
import { 
  FileUploader, 
  FileUploadParts, 
  createErrorMessages,
  Text,
} from '@cerberus/react'

const errorMessages = createErrorMessages({
  TOO_MANY_FILES: '📊 Too many files selected (max 3 allowed)',
  FILE_INVALID_TYPE: '🚫 Invalid file type (only images and PDFs allowed)',
  FILE_TOO_LARGE: '📏 File too large (max 1MB)',
  FILE_TOO_SMALL: '📐 File too small (min 1KB)',
  FILE_INVALID: '⚠️ Invalid file',
  FILE_EXISTS: '🔄 File already exists',
})

export const ErrorHandling = () => {
  return (
    <FileUploader 
      maxFiles={3}
      maxFileSize={1024 * 1024} // 1MB
      minFileSize={1024} // 1KB
      accept="image/*,application/pdf" 
      showPreview={false}
    >
      <div data-status="rejected">
        <Text textStyle="heading-md">❌ Rejected Files</Text>

        <FileUploadParts.ItemGroup>
          <FileUploadParts.Context>
            {({ rejectedFiles }) =>
              rejectedFiles.length === 0 ? (
                <Text>No rejected files</Text>
              ) : (
                rejectedFiles.map((fileRejection) => (
                  <FileUploadParts.Item
                    key={fileRejection.file.name}
                    file={fileRejection.file}
                    data-status="rejected"
                  >
                    <FileUploadParts.ItemName />
                    <FileUploadParts.ItemSizeText />
                    <div>
                      <Text as="strong">Validation Errors:</Text>
                      {fileRejection.errors.map((error, index) => (
                        <div key={index} data-error-code={error}>
                          {errorMessages[error as FileUploadFileError] || `❓ ${error}`}
                        </div>
                      ))}
                    </div>
                  </FileUploadParts.Item>
                ))
              )
            }
          </FileUploadParts.Context>
        </FileUploadParts.ItemGroup>
      </div>
    </FileUploader>
  )
}
```

### Error Helpers

To easily create error messages for the built-in error types, use the `createErrorMessages` function:

```typescript
createErrorMessages({
  tooMany: 'Too many files were selected',
  invalidType: 'This is not a valid file type',
  tooLarge: 'File size exceeds the maximum allowed (3KB)',
  tooSmall: 'File size must be at least 1KB',
  invalid: 'File type is not supported. Please select a valid file type.',
  exists: 'File already exists'
})
```

All of the properties within the options Object are optional and will provide the following
default error messages if not provided:

```typescript
{
  TOO_MANY_FILES: options.tooMany || '📊 Too many files selected',
  FILE_INVALID_TYPE: options.invalidType || '🚫 Invalid file type',
  FILE_TOO_LARGE: options.tooLarge || '📏 File too large',
  FILE_TOO_SMALL: options.tooSmall || '📐 File too small',
  FILE_INVALID: options.invalid || '⚠️ Invalid file',
  FILE_EXISTS: options.exists || '🔄 File already exists',
}
```

## File Transformations

Use the `transformFiles` prop to process files before they're added to the accepted files list. This is useful for file
compression, format conversion, or adding metadata.

**Common transformation use cases:**

- **Image compression**: Use `image-conversion`, `browser-image-compression`, or similar libraries
- **Format conversion**: Convert files to different formats (e.g., HEIC to JPEG)
- **Metadata extraction**: Add EXIF data or other file information
- **File validation**: Perform additional checks beyond basic validation
- **Resizing**: Automatically resize images to specific dimensions

```typescript



function FileTransformationsDemo() {
  const transformFiles = async (files: File[]) => {
    return Promise.all(
      files.map(async (file) => {
        if (file.type.startsWith('image/')) {
          try {
            // Compress image to ~200KB
            const blob = await compressAccurately(file, 200)
            return new File([blob], file.name, { type: blob.type })
          } catch (error) {
            console.error('Compression failed for:', file.name, error)
            return file
          }
        }
        return file // Return non-image files as-is
      }),
    )
  }

  return (
    <FileUploader 
      accept="image/*" 
      maxFiles={5} 
      transformFiles={transformFiles} 
    />
  )
}
```

### Custom Validation

Use the `validate` prop to implement custom validation logic beyond the built-in constraints.

```tsx
<FileUploadParts.Root
  validate={(file) => {
    if (file.name.length > 20) return ['FILE_NAME_TOO_LONG']
    return null
  }}
/>
```

## Guides

### File Previews

The `FileUpload` component provides flexible preview options for different file types. Use `ItemPreview` with type
matching to show appropriate previews based on file format.

**Preview Types:**

- `type="image/*"`: Shows image thumbnails using `ItemPreviewImage`
- `type="video/*"`: For video file previews
- `type="application/pdf"`: For PDF files
- `type=".*"`: Generic fallback for any file type

```tsx
<FileUploadParts.ItemPreview type="image/*">
  <FileUploadParts.ItemPreviewImage />
</FileUploadParts.ItemPreview>

<FileUploadParts.ItemPreview type="video/*">
  <VideoIcon />
</FileUploadParts.ItemPreview>

<FileUploadParts.ItemPreview type="application/pdf">
  <PdfIcon />
</FileUploadParts.ItemPreview>

<FileUploadParts.ItemPreview type=".*">
  <FileIcon />
</FileUploadParts.ItemPreview>
```

**File Metadata Display:**

- `ItemName` - Shows the file name
- `ItemSizeText` - Shows formatted file size (e.g., "2.5 MB")

### Disable dropzone

To disable drag-and-drop functionality, set the `allowDrop` prop to `false`.

```tsx
<FileUploader allowDrop={false} />
```

### Prevent document drop

By default, when the dropzone is active, we prevent accidental navigation when files are dropped outside the dropzone.
To prevent this behavior, set the `preventDocumentDrop` prop to `false`.

```tsx
<FileUploader preventDocumentDrop={false} />
```

### Prevent double open

When you want to delegate clicking to the trigger and remove the dropzone from the tab order, you can use the
`disableClick` prop. This prevents the the file picker from opening twice.

```tsx
<FileUploadParts.Dropzone disableClick>
  <FileUploadParts.Trigger>Choose Files</FileUploadParts.Trigger>
  Drag files here
</FileUploadParts.Dropzone>
```

## Primitives

You can utilize the primitive components or the style props to customize the file uploader.

| Component | Description |
| --------- | ----------- |
| FileUploadRoot    | The context provider for the FileUploader parts |
| FileUploadTrigger   | The trigger of the FileUploader |
| FileUploadDropzone   | The dropzone of the FileUploader |
| FileUploadLabel   | The label of the FileUploader |
| FileUploadTrigger   | The trigger of the FileUploader |
| FileUploadClearTrigger | The clear trigger of the FileUploader |
| FileUPloadItemGroup | The container for the group of items |
| FileUploadItem | The container for the item |
| FileUploadItemPreview | The container of hte preview for the item |
| FileUploadItemPreviewImage | The image preview for the item |
| FileUploadItemName | The name of the item |
| FileUploadItemSizeText | The size text of the item |
| FileUploadItemDeleteTrigger | The delete trigger of the FileUploader |
| FileUPloadHiddenInput | The hidden input of the FileUploader |
| FileUploadContext | The context of the FileUploader |
| FileUploadIcon | The icon of the FileUploader |
| FileUploadHeading | The heading of the FileUploader |
| FileUploadDescription | The description of the FileUploader |

## API

### FileUploader

| Prop | Type |  Description |
|------|------|-------------|
| `accept` | `Record<string, string[]>` | The accept file types |
| `acceptedFiles` | `File[]` | The controlled accepted files |
| `allowDrop` | `boolean` | Whether to allow drag and drop in the dropzone element |
| `asChild` | `boolean` | Use the provided child element as the default rendered element, combining their props and behavior. |
| `capture` | `'user' or 'environment'` | The default camera to use when capturing media |
| `defaultAcceptedFiles` | `File[]` | The default accepted files when rendered. Use when you don't need to control the accepted files of the input. |
| `directory` | `boolean` | Whether to accept directories, only works in webkit browsers |
| `disabled` | `boolean` | Whether the file input is disabled |
| `ids` | `Partial<PrimitiveStack>` | The ids of the elements. Useful for composition. |
| `invalid` | `boolean` | Whether the file input is invalid |
| `locale` | `string` | The current locale. Based on the BCP 47 definition. |
| `maxFiles` | `number` | The maximum number of files |
| `maxFileSize` | `number` | The maximum file size in bytes |
| `minFileSize` | `number` | The minimum file size in bytes |
| `name` | `string` | The name of the underlying file input |
| `onFileAccept` | `(details: FileAcceptDetails) => void` | Function called when the file is accepted |
| `onFileChange` | `(details: FileChangeDetails) => void` | Function called when the value changes, whether accepted or rejected |
| `onFileReject` | `(details: FileRejectDetails) => void` | Function called when the file is rejected |
| `preventDocumentDrop` | `boolean` | Whether to prevent the drop event on the document |
| `required` | `boolean` | Whether the file input is required |
| `transformFiles` | `(files: File[]) => Promise<File[]>` | Function to transform the accepted files to apply transformations |
| `translations` | `IntlTranslations` | The localized messages to use. |
| `validate` | `(file: File, details: FileValidateDetails) => FileError[] or null` | Function to validate a file |
| `heading`  |   `string`     | The heading for the file uploader                             |
| `showPreview`     |     `boolean`    | Whether to show the preview of the file or custom children.                                  |

#### Root Data Attributes:

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | file-upload |
| `[data-part]` | root |
| `[data-disabled]` | Present when disabled |
| `[data-dragging]` | Present when in the dragging state |


### FileStatus

The `FileStatus` component accepts the following props:

| Name     | Default | Description                                                   |
| -------- | ------- | ------------------------------------------------------------- |
| `id`       |         | A unique identifier for the ProgressBar.            |
| `file`     |         | The name of the file being processed                          |
| `now`      |         | The current progress of the file upload                       |
| `status`   |    `'todo'`     | The status of the file upload                                 |


---
## flex

---
title: Flex
description: Used to manage flex layouts as an alternative to HStack and VStack.
panda: https://panda-css.com/docs/concepts/patterns#flex
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

Used to manage flex layouts


```tsx



export function BasicDemo() {
  return (
    <Flex gap="4" w="3/4">
      <DecorativeBox height="10" />
      <DecorativeBox height="10" />
      <DecorativeBox height="10" />
    </Flex>
  )
}
```


### Direction

Use the `direction` or `flexDirection` prop to change the direction of the flex


```tsx



export function DirectionDemo() {
  return (
    <Flex direction="column" gap="4" w="3/4">
      <DecorativeBox height="10" />
      <DecorativeBox height="10" />
      <DecorativeBox height="10" />
    </Flex>
  )
}
```


### Align

Use the `align` or `alignItems` prop to align the children along the cross axis.


```tsx



export function AlignDemo() {
  return (
    <Flex align="center" gap="4" w="3/4">
      <DecorativeBox height="4" />
      <DecorativeBox height="8" />
      <DecorativeBox height="10" />
    </Flex>
  )
}
```


### Justify

Use the `justify` or `justifyContent` prop to align the children along the main
axis.


```tsx



export function JustifyDemo() {
  return (
    <Flex direction="column" gap="lg" w="3/4">
      <Flex gap="4" justify="flex-start">
        <DecorativeBox height="10" width="120px" />
        <DecorativeBox height="10" width="120px">
          flex-start
        </DecorativeBox>
        <DecorativeBox height="10" width="120px" />
      </Flex>

      <Flex gap="4" justify="center">
        <DecorativeBox height="10" width="120px" />
        <DecorativeBox height="10" width="120px">
          center
        </DecorativeBox>
        <DecorativeBox height="10" width="120px" />
      </Flex>

      <Flex gap="4" justify="flex-end">
        <DecorativeBox height="10" width="120px" />
        <DecorativeBox height="10" width="120px">
          flex-end
        </DecorativeBox>
        <DecorativeBox height="10" width="120px" />
      </Flex>

      <Flex gap="4" justify="space-between">
        <DecorativeBox height="10" width="120px" />
        <DecorativeBox height="10" width="120px">
          space-between
        </DecorativeBox>
        <DecorativeBox height="10" width="120px" />
      </Flex>
    </Flex>
  )
}
```


### Order

Use the `order` prop to change the order of the children.


```tsx



export function OrderDemo() {
  return (
    <Flex gap="4" w="3/4">
      <DecorativeBox height="10" order="1">
        1
      </DecorativeBox>
      <DecorativeBox height="10" order="3">
        2
      </DecorativeBox>
      <DecorativeBox height="10" order="2">
        3
      </DecorativeBox>
    </Flex>
  )
}
```


### Auto Margin

Apply margin to a flex item to push it away from its siblings.


```tsx



export function MarginDemo() {
  return (
    <Flex gap="4" justify="space-between" w="3/4">
      <DecorativeBox height="10" width="40" />
      <DecorativeBox height="10" width="40" marginEnd="auto" />
      <DecorativeBox height="10" width="40" />
    </Flex>
  )
}
```


### Wrap

Use the `wrap` or `flexWrap` prop to wrap the children when they overflow the
parent.


```tsx



export function WrapDemo() {
  return (
    <Flex gap="4" wrap="wrap" maxW="500px" w="full">
      <DecorativeBox height="10" width="200px" />
      <DecorativeBox height="10" width="200px" />
      <DecorativeBox height="10" width="200px" />
    </Flex>
  )
}
```


## Props

The `Flex` component accepts any style properties along with the following props:

| Prop        | Type         | Description                                    |
|-------------|--------------|------------------------------------------------|
| `align`     | `SystemStyleObject['alignItems']` | The alignment of the children along the cross axis. |
| `direction` | `SystemStyleObject['flexDirection']` | The flex direction. |
| `justify`   | `SystemStyleObject['justifyContent']` | The alignment of the children along the main axis. |
| `wrap`      | `SystemStyleObject['flexWrap']` | The wrapping behavior of the children. |
| `basis`     | `SystemStyleObject['flexBasis']` | The flex behavior of the children. |
| `grow`      | `SystemStyleObject['flexGrow']` | The flex grow behavior of the children. |
| `shrink`    | `SystemStyleObject['flexShrink']` | The flex shrink behavior of the children. |


---
## float

---
title: Float
description: Used to anchor an element to the edge of a container.
panda: https://panda-css.com/docs/concepts/patterns#float
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

Used to anchor an element to the edge of a container.


```tsx


export function BasicDemo() {
  return (
    <Box position="relative" w="80px" h="80px" bg="page.surface.100">
      <Float>
        <Circle size="5" bg="red" color="white" textStyle="label-sm">
          3
        </Circle>
      </Float>
    </Box>
  )
}
```


### Placement

Use the `placement` prop to position the element along the edges of the
container.


```tsx

import {
  Box,
  Circle,
  Float,
  FloatProps,
  HStack,
  VStack,
} from 'styled-system/jsx'

export function PlacementsDemo() {
  const placements = [
    'bottom-end',
    'bottom-start',
    'top-end',
    'top-start',
    'bottom-center',
    'top-center',
    'middle-center',
    'middle-end',
    'middle-start',
  ] as const

  return (
    <HStack gap="14" flexWrap="wrap" px="md" pt="md" w="full">
      {placements.map((placement) => (
        <VStack key={placement} gap="sm" justify="center" pos="relative">
          <Box
            position="relative"
            width="80px"
            height="80px"
            bg="page.surface.100"
          >
            <MatchFloat placement={placement}>
              <Circle size="5" bg="red" color="white" textStyle="label-sm">
                3
              </Circle>
            </MatchFloat>
          </Box>
          <Text as="small" textStyle="label-sm">
            {placement}
          </Text>
        </VStack>
      ))}
    </HStack>
  )
}

function MatchFloat(props: FloatProps) {
  switch (props.placement) {
    case 'bottom-end':
      return <Float placement="bottom-end" {...props} />
    case 'bottom-start':
      return <Float placement="bottom-start" {...props} />
    case 'top-end':
      return <Float placement="top-end" {...props} />
    case 'top-start':
      return <Float placement="top-start" {...props} />
    case 'bottom-center':
      return <Float placement="bottom-center" {...props} />
    case 'top-center':
      return <Float placement="top-center" {...props} />
    case 'middle-center':
      return <Float placement="middle-center" {...props} />
    case 'middle-end':
      return <Float placement="middle-end" {...props} />
    case 'middle-start':
      return <Float placement="middle-start" {...props} />
    default:
      return null
  }
}
```


### Offset X

Use the `offsetX` prop to offset the element along the x-axis.


```tsx


export function OffsetXDemo() {
  return (
    <Box position="relative" w="80px" h="80px" bg="page.surface.100">
      <Float offsetX="-4">
        <Circle size="5" bg="red" color="white" textStyle="label-sm">
          3
        </Circle>
      </Float>
    </Box>
  )
}
```


### Offset Y

Use the `offsetY` prop to offset the element along the y-axis.


```tsx


export function OffsetYDemo() {
  return (
    <Box position="relative" w="80px" h="80px" bg="page.surface.100">
      <Float offsetY="-4">
        <Circle size="5" bg="red" color="white" textStyle="label-sm">
          3
        </Circle>
      </Float>
    </Box>
  )
}
```


### Offset

Use the `offset` prop to offset the element along both axes.


```tsx


export function OffsetDemo() {
  return (
    <Box position="relative" w="80px" h="80px" bg="page.surface.100">
      <Float offset="-4">
        <Circle size="5" bg="red" color="white" textStyle="label-sm">
          3
        </Circle>
      </Float>
    </Box>
  )
}
```


### Avatar

Here's an example of composing a `Float` component with an `Avatar` component.


```tsx



export function AvatarDemo() {
  return (
    <Box position="relative">
      <Avatar
        alt="User Avatar"
        src="https://avatars.githubusercontent.com/u/12345678?v=4"
        size="xl"
      />
      <Float placement="bottom-center" offsetY="-4px">
        <Tag>Listening to...</Tag>
      </Float>
    </Box>
  )
}
```


## Props

The `Float` component accepts any style properties along with the following props:

| Prop        | Type                | Description                                                                 |
|-------------|---------------------|-----------------------------------------------------------------------------|
| `placement` | `SystemStyleObject['float']` | The placement of the float element relative to its parent.                |
| `offsetX`   | `SystemStyleObject['marginInline']` | The offset along the x-axis.                                               |
| `offsetY`   | `SystemStyleObject['marginBlock']`  | The offset along the y-axis.                                                |
| `offset`    | `SystemStyleObject['margin']`       | The offset along both axes.                                                 |


---
## focus-trap

---
title: 'Focus Trap'
description: 'Contains focus within a designated container until explicitly released.'
npm: '@cerberus-design/react'
arkUtility: 'focus-trap'
---



## Motivation

Focus trapping is essential for modal interfaces and other interactive elements that require user attention.

The `FocusTrap` component helps maintain accessibility by ensuring keyboard focus remains within a designated container
until explicitly released.

## Examples

```tsx



export const Basic = () => {
  const [trapped, setTrapped] = useState(false)
  return (
    <>
      <button onClick={() => setTrapped(true)}>Start Trap</button>
      <FocusTrap returnFocusOnDeactivate={false} disabled={!trapped}>
        <div
          style={{
            display: 'flex',
            flexDirection: 'column',
            gap: '1rem',
            paddingBlock: '1rem',
          }}
        >
          <input type="text" placeholder="input" />
          <textarea placeholder="textarea" />
          <button onClick={() => setTrapped(false)}>End Trap</button>
        </div>
      </FocusTrap>
    </>
  )
}

```

### Autofocus

The focus trap respects elements with the `autofocus` attribute.

```tsx



export const Autofocus = () => {
  const [trapped, setTrapped] = useState(false)
  const toggle = () => setTrapped((c) => !c)

  const buttonRef = useRef<HTMLButtonElement | null>(null)
  const getButtonNode = () => {
    const node = buttonRef.current
    if (!node) throw new Error('Button not found')
    return node
  }

  return (
    <div>
      <button ref={buttonRef} onClick={toggle}>
        {trapped ? 'End Trap' : 'Start Trap'}
      </button>
      {trapped && (
        <FocusTrap disabled={!trapped} setReturnFocus={getButtonNode}>
          <div
            style={{
              display: 'flex',
              flexDirection: 'column',
              gap: '1rem',
              paddingBlock: '1rem',
            }}
          >
            <input type="text" placeholder="Regular input" />
            {/* biome-ignore lint/a11y/noAutofocus: intentional */}
            <input type="text" placeholder="Autofocused input" autoFocus />
            <button onClick={() => setTrapped(false)}>End Trap</button>
          </div>
        </FocusTrap>
      )}
    </div>
  )
}

```



### Initial Focus

Use the `initialFocus` prop to set the element that should receive initial focus when the trap is activated.

```tsx



export const InitialFocus = () => {
  const [trapped, setTrapped] = useState(false)
  const toggle = () => setTrapped((c) => !c)

  const inputRef = useRef<HTMLInputElement>(null)

  return (
    <div>
      <button onClick={toggle}>{trapped ? 'End Trap' : 'Start Trap'}</button>
      <FocusTrap disabled={!trapped} initialFocus={() => inputRef.current}>
        <div
          style={{
            display: 'flex',
            flexDirection: 'column',
            gap: '1rem',
            paddingBlock: '1rem',
          }}
        >
          <input type="text" placeholder="First input" />
          <input ref={inputRef} type="text" placeholder="Second input (initial focus)" />
          <textarea placeholder="textarea" />
          <button onClick={() => setTrapped(false)}>End Trap</button>
        </div>
      </FocusTrap>
    </div>
  )
}

```



## API Reference

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `disabled` | `boolean` | No | Whether the focus trap is disabled. |
| `fallbackFocus` | `FocusTarget` | No | By default, an error will be thrown if the focus trap contains no
elements in its tab order. With this option you can specify a
fallback element to programmatically receive focus if no other
tabbable elements are found. For example, you may want a popover's
`<div>` to receive focus if the popover's content includes no
tabbable elements. *Make sure the fallback element has a negative
`tabindex` so it can be programmatically focused.|
| `initialFocus` | `VoidFunction` | No | By default, when a focus trap is activated the first element in the
focus trap's tab order will receive focus. With this option you can
specify a different element to receive that initial focus, or use `false`
for no initially focused element at all. |
| `onActivate` | `VoidFunction` | No | A function that will be called **before** sending focus to the
target element upon activation. |
| `onDeactivate` | `VoidFunction` | No | A function that will be called **before** sending focus to the
trigger element upon deactivation. |
| `returnFocusOnDeactivate` | `boolean` | No | Default: `true`. If `false`, when the trap is deactivated,
focus will *not* return to the element that had focus before activation. |
| `setReturnFocus` |  | No | By default, focus trap on deactivation will return to the element that was focused before activation. |

> **Note:** If `initialFocus` is `false` (or a function that returns `false`),
this function will not be called when the trap is activated, and no element
will be initially focused. This function may still be called while the trap
is active if things change such that there are no longer any tabbable nodes
in the trap.


---
## for

---
title: 'For'
description: 'Render a list of components or a fallback. Inspired by SolidJS.'
npm: '@cerberus-design/react'
source: 'components/for'
---




```ts

```

## Usage

The `For` component is used to render a list of components or a fallback. It is an abstraction of the `Array.map` method.

}>
```tsx title="for demo"



function ForPreview() {
  const data = ['Cerberus', 'Design', 'System', 'Roolz', 'D00dz']

  return (
    <VStack alignItems="flex-start" gap="md">
      <For each={data}>
        {(item, index) => (
          <Text key={item} textStyle="body-lg">
            {index}. {item}
          </Text>
        )}
      </For>
    </VStack>
  )
}
```


## API

```ts showLineNumbers=false
export interface ForProps {
  each: any[]
  fallback?: ReactNode
}

define function For(props: ForProps): ReactNode | null
```

### Props

The `For` component accepts the following props:

| Name     | Default | Description                                           |
| -------- | ------- | ------------------------------------------------- |
| each     |         | An Array of items to loop through. |
| fallback | null    | The content to render when the each value is empty. |


---
## format-byte

---
title: 'Format Byte'
description: 'Formats a byte value with automatic unit conversion and display options.'
npm: '@cerberus/react'
arkUtility: 'format-byte'
---




## Usage

The byte formatting component extends the number formatting capabilities to handle byte-specific formatting, including
automatic unit conversion and display options.

```jsx

```

## Examples

### Basic

Use the `Format.Byte` component to format a byte value with default options.

} />
```tsx
'use client'



export const ByteBasic = () => {
  return (
    <div>
      File size: <Format.Byte value={1450.45} />
    </div>
  )
}

```

### Sizes

Use the `sizes` prop to specify custom byte sizes for formatting.

```tsx
'use client'



export const ByteSizes = () => {
  const byteSizes = [50, 5000, 5000000, 5000000000]

  return (
    <div>
      {byteSizes.map((size, index) => (
        <div key={index}>
          <Format.Byte value={size} />
        </div>
      ))}
    </div>
  )
}
```

### Locale

Use the `locale` prop to format the byte value according to a specific locale.

```tsx
'use client'



export const ByteWithLocale = () => {
  const locales = ['de-DE', 'zh-CN']
  const value = 1450.45

  return (
    <div>
      {locales.map((locale) => (
        <LocaleProvider key={locale} locale={locale}>
          <Format.Byte value={value} />
        </LocaleProvider>
      ))}
    </div>
  )
}
```

### Unit

Use the `unit` prop to specify the unit of the byte value.

```tsx
'use client'



export const ByteWithUnit = () => {
  const value = 1450.45
  const unit = 'bit'

  return (
    <div>
      File size: <Format.Byte value={value} unit={unit} />
    </div>
  )
}
````

### Unit Display

Use the `unitDisplay` prop to specify the display of the unit.

```tsx
'use client'



export const ByteWithUnitDisplay = () => {
  const value = 50345.53
  const unitDisplays = ['narrow', 'short', 'long'] as const

  return (
    <div>
      {unitDisplays.map((unitDisplay) => (
        <Format.Byte key={unitDisplay} value={value} unitDisplay={unitDisplay} />
      ))}
    </div>
  )
}
```


---
## format-number

---
title: 'Format Number'
description: 'Formats a number value with automatic unit conversion and display options.'
npm: '@cerberus/react'
arkUtility: 'format-number'
---




## Usage

The number formatting logic is handled by the native `Intl.NumberFormat` API and smartly cached to avoid performance
issues when using the same locale and options.

```jsx

```

## Examples

### Basic

Use the `Format.Number` component to format a number with default options.

} />
```tsx
'use client'



export const NumberBasic = () => {
  return <Format.Number value={1450.45} />
}
```

### Percentage

Use the `style="percent"` prop to format the number as a percentage.

```tsx
'use client'



export const NumberWithPercentage = () => {
  return <Format.Number value={0.145} style="percent" maximumFractionDigits={2} minimumFractionDigits={2} />
}
```

### Currency

Use the `style="currency"` prop along with the `currency` prop to format the number as a currency.

```tsx
'use client'



export const NumberWithCurrency = () => {
  return <Format.Number value={1234.45} style="currency" currency="USD" />
}
```

### Locale

Use the `locale` prop to format the number according to a specific locale.

```tsx
'use client'



export const NumberWithLocale = () => {
  return (
    <LocaleProvider locale="de-DE">
      <Format.Number value={1450.45} />
    </LocaleProvider>
  )
}
```

### Unit

Use the `style="unit"` prop along with the `unit` prop to format the number with a specific unit.

```tsx
'use client'



export const NumberWithUnit = () => {
  return <Format.Number value={384.4} style="unit" unit="kilometer" />
}

```

### Compact Notation

Use the `notation="compact"` prop to format the number in compact notation.

```tsx
'use client'



export const NumberWithCompact = () => {
  return <Format.Number value={1500000} notation="compact" compactDisplay="short" />
}
```


---
## format-relative-time

---
title: 'Format Relative Time'
description: Format relative time using the native `Intl.RelativeTimeFormat` API.
npm: '@cerberus/react'
arkUtility: 'format-relative-time'
---




## Usage

The relative time formatting logic is handled by the native `Intl.RelativeTimeFormat` API and smartly cached to avoid
performance issues when using the same locale and options.

```jsx

```

## Examples

### Basic

Use the `Format.RelativeTime` component to format a relative time with default options.

} />
```tsx
'use client'



export const RelativeTimeBasic = () => {
  return (
    <div>
      Edited <Format.RelativeTime value={new Date('2025-05-05')} />
    </div>
  )
}
```

### Short

Use the `style="short"` prop to format the relative time in short format.

} />
```tsx
'use client'



export const RelativeTimeShort = () => {
  return (
    <div>
      Edited <Format.RelativeTime value={new Date('2025-05-05')} style="short" />
    </div>
  )
}
```


---
## frame

---
title: 'Frame'
description: Used to render a component in an iframe
npm: '@cerberus/react'
arkUtility: 'frame'
---

## Usage

The `Frame` component is used to render a component in an iframe.

- Tracks the size of the content and exposes them via css variables.
- Support for `head` prop to inject scripts and styles.
- Support for mount and unmount callbacks.

```jsx

```

## Examples

### Basic

Wrap your component in the `Frame` component to render it in an iframe.

```tsx


export const Basic = () => {
  return (
    <Frame
      title="Custom Frame"
      style={{ border: '1px solid #ccc', width: '100%', height: 'var(--height)' }}
      head={<style>{'body { background-color: #f0f0f0; }'}</style>}
    >
      <div style={{ padding: '40px' }}>
        <h1>Hello from inside the frame!</h1>
        <p>This content is rendered within our custom frame component using a Portal.</p>
      </div>
    </Frame>
  )
}
```

### Injecting Script

Using the `onMount` prop, you can inject a script into the iframe.

```tsx



export const Script = () => {
  const ref = useRef<HTMLIFrameElement>(null)
  return (
    <Frame
      ref={ref}
      title="Custom Frame"
      onMount={() => {
        const doc = ref.current?.contentDocument
        if (!doc) return
        const script = doc.createElement('script')
        script.innerHTML = 'console.log("Hello from inside the frame!")'
        doc.body.appendChild(script)
      }}
      style={{ border: '1px solid #ccc', width: '100%', height: 'var(--height)' }}
    >
      <div style={{ padding: '40px' }}>
        <h1>Hello from inside the frame!</h1>
        <p>This content is rendered within our custom frame component using a Portal.</p>
      </div>
    </Frame>
  )
```

### Custom src doc

Use the `srcDoc` prop to specify the HTML content of the page to use in the iframe.

```tsx


const srcDoc = `<html><head>
<link href="//use.fontawesome.com/releases/v5.15.1/css/all.css" rel="stylesheet" />
<link href="//fonts.googleapis.com/css?family=Open+Sans:400,300,600,700" rel="stylesheet" type="text/css" />
<base target=_blank>
</head><body style='overflow: hidden'><div></div></body></html>`

export const SrcDoc = () => {
  return (
    <Frame title="Custom Frame" style={{ border: '1px solid #ccc', maxWidth: '800px', width: '100%' }} srcDoc={srcDoc}>
      <h1 style={{ fontFamily: 'Open Sans, sans-serif' }}>Hello from inside the frame!</h1>
      <p>This content is rendered within our custom frame component using a Portal.</p>
      <p>The frame has custom initial content, including Font Awesome and Open Sans font.</p>
    </Frame>
  )
}
```

## API Reference

### Props

**Component API Reference**


| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `head` | `any`  | No | Additional content to be inserted into the frame's `<head>` |
| `onMount` | `() => void` | No | Callback function to be executed when the frame is mounted |
| `onUnmount` | `() => void` | No | Callback function to be executed when the frame is unmounted |


---
## grid

---
title: Grid
description: Used to manage grid layouts.
panda: https://panda-css.com/docs/concepts/patterns#grid
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

Easily create grid layouts with the `Grid` component.


```tsx



export function BasicDemo() {
  return (
    <Grid gridTemplateColumns="repeat(3, 1fr)" gap="md" w="3/4">
      <DecorativeBox h="20" />
      <DecorativeBox h="20" />
      <DecorativeBox h="20" />
    </Grid>
  )
}
```


### Col Span

Pass `colSpan` prop to `GridItem` to span across columns.


```tsx



export function ColSpanDemo() {
  return (
    <Grid gridTemplateColumns="repeat(4, 1fr)" gap="md" w="3/4">
      <GridItem colSpan={2}>
        <DecorativeBox h="20" />
      </GridItem>
      <GridItem colSpan={1}>
        <DecorativeBox h="20" />
      </GridItem>
      <GridItem colSpan={1}>
        <DecorativeBox h="20" />
      </GridItem>
    </Grid>
  )
}
```


### Spanning Columns

In some layouts, you may need certain grid items to span specific amount of
columns or rows instead of an even distribution


```tsx



export function SpanningDemo() {
  return (
    <Grid
      h="200px"
      gridTemplateRows="repeat(2, 1fr)"
      gridTemplateColumns="repeat(5, 1fr)"
      gap="md"
      w="3/4"
    >
      <GridItem rowSpan={2} colSpan={1}>
        <DecorativeBox>rowSpan=2</DecorativeBox>
      </GridItem>
      <GridItem colSpan={2}>
        <DecorativeBox>colSpan=2</DecorativeBox>
      </GridItem>
      <GridItem colSpan={2}>
        <DecorativeBox>colSpan=2</DecorativeBox>
      </GridItem>
      <GridItem colSpan={4}>
        <DecorativeBox>colSpan=4</DecorativeBox>
      </GridItem>
    </Grid>
  )
}
```


## Props

| Prop                | Type                                       | Description                                  |
| ------------------- | ------------------------------------------ | -------------------------------------------- |
| gridTemplateColumns | `SystemStyleObject['gridTemplateColumns']` | Defines the columns of the grid.             |
| gridTemplateRows    | `SystemStyleObject['gridTemplateRows']`    | Defines the rows of the grid.                |
| gap                 | `SystemStyleObject['gap']`                 | Defines the gap between grid items.          |
| colSpan             | `number`                                   | Number of columns the grid item should span. |
| rowSpan             | `number`                                   | Number of rows the grid item should span.    |
| columns             | `number`                                   | Number of columns in the grid.               |


---
## group

---
title: Group
description: Used to layout its children in an attached or normal group.
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

Used to group and attach elements together.


```tsx



export function BasicDemo() {
  return (
    <Group>
      <DecorativeBox h="20" w="40">
        1
      </DecorativeBox>
      <DecorativeBox h="20" w="40">
        2
      </DecorativeBox>
    </Group>
  )
}
```


## Attached

Use the `layout` prop to attach the group of children together.


```tsx



export function AttachedDemo() {
  return (
    <VStack gap="md" w="3/4">
      <Group layout="attached">
        <Button usage="outlined">Item 1</Button>
        <Button usage="outlined">Item 2</Button>
      </Group>

      <Group layout="attached">
        <Tag usage="filled">Commit status</Tag>
        <Tag usage="filled" palette="success">
          90+
        </Tag>
      </Group>
    </VStack>
  )
}
```


## Grow

Use the `grow` variant of the `layout` prop to make the children fill the space.


```tsx


export function GrowDemo() {
  return (
    <Group layout="grow" w="3/4">
      <Button usage="outlined">First</Button>
      <Button usage="outlined">Second</Button>
      <Button usage="outlined">Third</Button>
    </Group>
  )
}
```


## Orientation

Use the `orientation` prop to change the direction of the children.


```tsx



export function OrientationDemo() {
  return (
    <Group orientation="vertical">
      <DecorativeBox h="20" w="40">
        1
      </DecorativeBox>
      <DecorativeBox h="20" w="40">
        2
      </DecorativeBox>
    </Group>
  )
}
```


## Stack

Use the `stack` variant of the `layout` with `orientation` to stack the children.


```tsx





export function StackDemo() {
  return (
    <HStack gap="xl">
      <Group layout="stack" orientation="horizontal">
        <Box>1</Box>
        <Box>2</Box>
      </Group>

      <Group layout="stack" orientation="vertical">
        <Box>1</Box>
        <Box>2</Box>
      </Group>
    </HStack>
  )
}

function Box({ children }: PropsWithChildren<object>) {
  return (
    <DecorativeBox h="12" w="12">
      {children}
    </DecorativeBox>
  )
}
```


## Props

The `Group` component accepts any style properties along with the following props:

| Prop          | Type                                   | Description                                                                                         |
| ------------- | -------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `layout`      | `default \| attached \| grow \| stack` | The layout of the children along the cross axis.                                                    |
| `orientation` | `horizontal, vertical`                 | The direction of the children.                                                                      |
| `asChild`     | `boolean`                              | Use the provided child element as the default rendered element, combining their props and behavior. |


---
## highlight

---
title: 'Highlight'
description: 'Highlight text with query'
npm: '@cerberus/react'
arkUtility: 'highlight'
---




## Usage

The Highlight component takes a `text` prop containing the full text and a `query` prop specifying the text to
highlight. It then renders the text with highlighted portions wrapped in `<mark>` tags.

} />
```tsx


export const Basic = () => {
  return (
    <Highlight
      query="ipsum"
      text="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt"
    />
  )
}
```

### Multiple Queries

You can highlight multiple terms by passing an array of strings to the `query` prop.

```tsx


export const Multiple = () => {
  return (
    <Highlight
      query={['ipsum', 'amet']}
      text="Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt"
    />
  )
}

```


### Case Sensitivity

By default, the highlighting is case-sensitive. Use the `ignoreCase` prop to make it case-insensitive.


```tsx


export const IgnoreCase = () => (
  <Highlight text="The quick brown Fox jumps over the lazy Dog." query={['fox', 'dog']} ignoreCase />
)

```


### Match All

By default, the Highlight component matches the first occurrence of the query. To highlight all occurrences of the
query, set the `matchAll` prop to `true`.



```tsx


export const MatchAll = () => (
  <div>
    <h3>Match All</h3>
    <Highlight text="The quick brown fox jumps over the lazy fox." query="fox" matchAll={true} />

    <h3>Match First Occurrence Only</h3>
    <Highlight text="The quick brown fox jumps over the lazy fox." query="fox" matchAll={false} />
  </div>
)

```

### Exact Match

By default, the Highlight component matches partial words. Use the `exactMatch` prop to only highlight whole words that
match the query exactly.


```tsx


export const ExactMatch = () => {
  return (
    <div>
      <p>Without exactMatch (highlights partial matches):</p>
      <Highlight query="cat" text="The cat is in the category. A cat-like creature." matchAll />
      <p style={{ marginTop: '1rem' }}>With exactMatch (highlights whole words only):</p>
      <Highlight query="cat" text="The cat is in the category. A cat-like creature." exactMatch matchAll />
    </div>
  )
}

```

## API Reference

**Highlight Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `query` | `string[]` | Yes | The query to highlight in the text |
| `text` | `string` | Yes | The text to highlight |
| `exactMatch` | `boolean` | No | Whether to match whole words only |
| `ignoreCase` | `boolean` | No | Whether to ignore case while matching |
| `matchAll` | `boolean` | No | Whether to match multiple instances of the query |


## Customization

The Highlight component wraps matched text in `<mark>` tags.

```tsx
<Highlight text="The quick brown fox jumps over the lazy fox." query="fox" className="highlighted-text" />
```

Style the `mark` tags using CSS to customize the appearance of highlighted text.

```css
.highlighted-text {
  background-color: yellow;
}
```


---
## icon-button

---
title: 'IconButton'
description: 'The IconButton component is a button that displays an icon.'
npm: '@cerberus-design/react'
source: 'components/icon-button'
recipe: 'iconButton.ts'
---



import {
  BasicButtonPreview,
  SizesDemo,
  AsChildDemo,
  CustomButtonPreview,
} from '../components/icon-button/static'

```ts

```

## Usage

}>
```tsx title="button.tsx"



function BasicButtonPreview() {
  return <IconButton><Tuning /></IconButton>
}
```


## Sizes

The `IconButton` component comes in two sizes: `sm`, `lg`. You can set the size by using the `size` prop.

}>
```tsx title="button.tsx"




function SizesDemo() {
  return (
    <HStack>
      <IconButton size="sm" usage="filled">
        <Tuning />
      </IconButton>
      <IconButton size="lg" usage="filled">
        <Tuning />
      </IconButton>
    </HStack>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the button.

| Component | Description |
| --------- | ----------- |
| IconButton    | The context provider for the Button parts |

}>
```tsx title="custom demo"



function CustomButtonPreview() {
  return (
    <IconButton
      ariaLabel="custom button"
      css={{
        bgColor: 'danger.bg.initial',
        color: 'danger.text.initial',
        rounded: 'md',
        transform: 'skew(-10deg)',
        _hover: {
          bgColor: 'black',
          color: 'yellow',
        },
      }}
    >
      <Tuning />
    </IconButton>
  )
}
```


## API

### Props

The `IconButton` component is an abstraction of the primitives and accepts the following props:

| Name     | Default | Description                            |
| -------- | ------- | -------------------------------------- |
| clipboard |     false    | If true, uses Clipboard aria-attributes.    |
| palette     | `action`   | The color palette (any of the Cerberus palettes) of the button. |
| usage | `filled`    | The style treatment of the button.    |
| shape | `sharp`     | The shape of the button.              |


---
## input

---
title: Input
description: The Input component displays a text-based input field.
npm: '@cerberus-design/react'
source: 'components/field'
recipe: 'slots/field.ts'
ark: 'field'
---







```ts
import {
  Field,
  Input,
} from '@cerberus/react'
```

## Usage

The `Input` component displays a text-based input field.

}>
```tsx title="some-form.tsx"



export function BasicFieldPreview() {
  return (
    <form action={someAction} method="post">
      <Box w="1/2">
        <VStack alignItems="flex-start" gap="lg" w="full">
          <Field
            label="Enter your email"
            helperText="We'll never share your email with anyone else."
            required
          >
            <Input name="email" type="email" />
          </Field>
          <Field
            label="Invalid example"
            helperText="This is an example of an invalid field."
            errorText="A name is required to submit this form. It replaces the helper text."
            invalid
            required
          >
            <Input name="invalid-name" type="text" />
          </Field>
          <Field
            label="Anything else you want to tell us?"
            helperText="This will help us learn more about you."
            secondaryHelperText="0/300"
          >
            <Textarea name="message" />
          </Field>
        </VStack>
      </Box>
    </form>
  )
}
```


## With Icons

You can utilize the `startIcon` or `endIcon` props to add icons to the input. 

}>
```tsx title="search-input.tsx"




export function SearchInputExample() {
  return (
    <VStack gap="md" w="1/2">
      <Field>
        <Input startIcon={<Search />} placeholder="Search for anything" />
      </Field>
      <Field>
        <Input endIcon={<Search />} placeholder="Search for anything" />
      </Field>
      <Field invalid>
        <Input endIcon={<Search />} placeholder="Search for anything" />
      </Field>
    </VStack>
  )
}
```


> **Note:** When and input is marked as invalid, the endIcon will be replaced by the invalid icon.

## Customizing

You can customize the input by passing styles directly into the component. The Input is a re-export of the `FieldInput` primitive.

}>
```tsx



export function CustomField() {
  return (
    <Box w="1/2">
      <FieldParts.Root>
        <FieldParts.Label
          css={{
            fontSize: 'xl',
            fontWeight: 'black',
            textTransform: 'uppercase',
          }}
        >
          Custom Label
        </FieldParts.Label>
        <FieldParts.Input
          css={{
            transform: 'skewX(-10deg)',
          }}
          type="text"
        />
        <FieldParts.HelperText
          css={{
            fontStyle: 'italic',
          }}
        >
          Custom Helper Text
        </FieldParts.HelperText>
      </FieldParts.Root>
    </Box>
  )
}
```



## API

### Props

The `Input` accepts the following props in addition to any native `input` props:

| Name     | Default | Description                            |
| -------- | ------- | -------------------------------------- |
| startIcon     |    | An `ElementType` to display at the start of the input |
| endIcon     |    | An `ElementType` to display at the end of the input |
| size     |  | This size variant of the input |

The `Input` component also accepts any of the props from the [`FieldParts.Input` primitive](https://ark-ui.com/react/docs/components/field#api-reference).


---
## json-tree-view

---
title: 'JSON Tree View'
description: 'A component that displays a JSON object in a tree-like structure.'
npm: '@cerberus/react'
arkUtility: 'json-tree-view'
---




## Examples

Learn how to use the `JsonTreeView` component in your project. Let's take a look at the most basic example:

} />
```tsx
'use client'




export const Basic = () => {
  return (
    <JsonTreeView.Root
      data={{
        name: 'John Doe',
        age: 30,
        email: 'john.doe@example.com',
        tags: ['tag1', 'tag2', 'tag3'],
        address: {
          street: '123 Main St',
          city: 'Anytown',
          state: 'CA',
          zip: '12345',
        },
      }}
    >
      <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
  )
}
```

### Different Data Types

The JSON tree view can display various JavaScript data types including objects, arrays, primitives, and special values:

```tsx
'use client'




const testArray = [1, 2, 3, 4, 5]
Object.defineProperties(testArray, {
  customProperty: { value: 'custom value', enumerable: false, writable: false },
  anotherProperty: { value: 42, enumerable: false, writable: false },
})

export const ArrayData = () => {
  return (
    <JsonTreeView.Root
      data={{
        normalArray: [1, 2, 3],
        arrayWithNonEnumerableProperties: testArray,
        sparseArray: (() => {
          const sparse = []
          sparse[0] = 'first'
          sparse[5] = 'sixth'
          return sparse
        })(),
      }}
    >
      <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
  )
}

```

### Functions and Methods

Display JavaScript functions, async functions, and generators in your JSON tree:

```tsx
'use client'




const data = [
  function sum(a: number, b: number) {
    return a + b
  },
  async (promises: Promise<any>[]) => await Promise.all(promises),
  function* generator(a: number) {
    while (a > 0) {
      yield a - 1
    }
  },
]

export const Functions = () => {
  return (
    <JsonTreeView.Root data={data}>
      <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
  )
}

```

### Regular Expressions

Regular expressions are displayed with their pattern and flags:

```tsx
'use client'




const data = {
  regex: /^[a-z0-9]+/g,
  case_insensitive: /^(?:[a-z0-9]+)foo.*?/i,
}

export const Regex = () => {
  return (
    <JsonTreeView.Root data={data}>
      <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
  )
}

```

### Error Objects

Error objects and their stack traces can be visualized:

```tsx
'use client'




const data = new Error('Error')

export const Errors = () => {
  return (
    <JsonTreeView.Root data={data}>
      <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
  )
}

```

### Map and Set Objects

Native JavaScript Map and Set objects are supported:

```tsx
'use client'




const data = new Map<string, any>([
  ['name', 'ark-ui-json-tree'],
  ['license', 'MIT'],
  ['elements', new Set(['ark-ui', 123, false, true, null, undefined, 456n])],
  [
    'nested',
    new Map<string, any>([
      [
        'taglines',
        new Set([
          { name: 'ark-ui', feature: 'headless components' },
          { name: 'ark-ui', feature: 'framework agnostic' },
          { name: 'ark-ui', feature: 'accessible by default' },
        ]),
      ],
    ]),
  ],
])

export const MapAndSet = () => {
  return (
    <JsonTreeView.Root data={data}>
      <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
  )
}

```

### Controlling Expand Level

Use the `defaultExpandedDepth` prop to control how many levels are expanded by default:

```tsx
'use client'




export const ExpandLevel = () => {
  return (
    <JsonTreeView.Root
      defaultExpandedDepth={1}
      data={{
        name: 'John Doe',
        age: 30,
        email: 'john.doe@example.com',
        tags: ['tag1', 'tag2', 'tag3'],
        address: {
          street: '123 Main St',
          city: 'Anytown',
          state: 'CA',
          zip: '12345',
        },
      }}
    >
      <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.Root>
  )
}

```


### Custom Value Rendering

You can customize how specific values are rendered using the `renderValue` prop. This example shows how to make email
addresses clickable:

```tsx
'use client'




export const RenderValue = () => {
  return (
    <JsonTreeView.Root
      defaultExpandedDepth={2}
      data={{
        name: 'John Doe',
        age: 30,
        number: Number.NaN,
        email: 'john.doe@example.com',
        address: {
          street: '123 Main St',
          city: 'Anytown',
          state: 'CA',
          zip: '12345',
        },
      }}
    >
      <JsonTreeView.Tree
        arrow={<ChevronRight />}
        renderValue={(node) => {
          if (node.type === 'text' && typeof node.value === 'string' && isEmail(node.value)) {
            return (
              <a href={`mailto:${node.value}`} target="_blank" rel="noreferrer">
                {node.value}
              </a>
            )
          }
        }}
      />
    </JsonTreeView.Root>
  )
}

const isEmail = (value: string) => {
  const strippedValue = value.replace(/^"(.*)"$/, '$1')
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(strippedValue)
}

```

### Configuration Options

The JSON tree view supports several configuration options to customize the display:

```tsx
<JsonTreeView.Root
  data={data}
  defaultExpandedDepth={2}
  quotesOnKeys={true}
  showNonenumerable={true}
  maxPreviewItems={5}
  collapseStringsAfterLength={50}
  groupArraysAfterLength={100}
>
  <JsonTreeView.Tree arrow={<ChevronRight />} />
</JsonTreeView.Root>
```

**Configuration Options:**

- **`quotesOnKeys`**: Whether to show quotes around object keys
- **`showNonenumerable`**: Whether to show non-enumerable properties
- **`maxPreviewItems`**: Maximum number of items to show in object/array previews
- **`collapseStringsAfterLength`**: Collapse strings longer than this length
- **`groupArraysAfterLength`**: Group array items when array is longer than this length

### Using the Root Provider

The `RootProvider` component provides a context for the JSON tree view. It accepts the value of the `useJsonTreeView`
hook. You can leverage it to access the component state and methods from outside the JSON tree view.

```tsx
'use client'




export const RootProvider = () => {
  const jsonTreeView = useJsonTreeView({
    data: {
      name: 'John Doe',
      age: 30,
      email: 'john.doe@example.com',
      tags: ['tag1', 'tag2', 'tag3'],
      address: {
        street: '123 Main St',
        city: 'Anytown',
        state: 'CA',
        zip: '12345',
      },
    },
  })

  return (
    <JsonTreeView.RootProvider value={jsonTreeView}>
      <JsonTreeView.Tree arrow={<ChevronRight />} />
    </JsonTreeView.RootProvider>
  )
}

```

> If you're using the `RootProvider` component, you don't need to use the `Root` component.

## API Reference

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `canRename` | `(node: JsonNode<any>, indexPath: IndexPath) => boolean` | No | Function to determine if a node can be renamed |
| `checkedValue` | `string[]` | No | The controlled checked node value |
| `collapseStringsAfterLength` | `number` | No |  |
| `data` | `{}` | No | The data to display in the tree. |
| `defaultCheckedValue` | `string[]` | No | The initial checked node value when rendered.
Use when you don't need to control the checked node value. |
| `defaultExpandedDepth` | `number` | No | The default expand level. |
| `defaultExpandedValue` | `string[]` | No | The initial expanded node ids when rendered.
Use when you don't need to control the expanded node value. |
| `defaultFocusedValue` | `string` | No | The initial focused node value when rendered.
Use when you don't need to control the focused node value. |
| `defaultSelectedValue` | `string[]` | No | The initial selected node value when rendered.
Use when you don't need to control the selected node value. |
| `expandedValue` | `string[]` | No | The controlled expanded node ids |
| `expandOnClick` | `boolean` | No | Whether clicking on a branch should open it or not |
| `focusedValue` | `string` | No | The value of the focused node |
| `groupArraysAfterLength` | `number` | No |  |
| `ids` | `Partial<{ root: string; tree: string; label: string; node: (value: string) => string }>` | No | The ids of the tree elements. Useful for composition. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `loadChildren` | `(details: LoadChildrenDetails<JsonNode<any>>) => Promise<JsonNode<any>[]>` | No | Function to load children for a node asynchronously.
When provided, branches will wait for this promise to resolve before expanding. |
| `maxPreviewItems` | `number` | No |  |
| `onBeforeRename` | `(details: RenameCompleteDetails) => boolean` | No | Called before a rename is completed. Return false to prevent the rename. |
| `onCheckedChange` | `(details: CheckedChangeDetails) => void` | No | Called when the checked value changes |
| `onExpandedChange` | `(details: ExpandedChangeDetails<JsonNode<any>>) => void` | No | Called when the tree is opened or closed |
| `onFocusChange` | `(details: FocusChangeDetails<JsonNode<any>>) => void` | No | Called when the focused node changes |
| `onLoadChildrenComplete` | `(details: LoadChildrenCompleteDetails<JsonNode<any>>) => void` | No | Called when a node finishes loading children |
| `onLoadChildrenError` | `(details: LoadChildrenErrorDetails<JsonNode<any>>) => void` | No | Called when loading children fails for one or more nodes |
| `onRenameComplete` | `(details: RenameCompleteDetails) => void` | No | Called when a node label rename is completed |
| `onRenameStart` | `(details: RenameStartDetails<JsonNode<any>>) => void` | No | Called when a node starts being renamed |
| `onSelectionChange` | `(details: SelectionChangeDetails<JsonNode<any>>) => void` | No | Called when the selection changes |
| `quotesOnKeys` | `boolean` | No | Whether to show quotes on the keys. |
| `selectedValue` | `string[]` | No | The controlled selected node value |
| `selectionMode` | `'single' | 'multiple'` | No | Whether the tree supports multiple selection
- "single": only one node can be selected
- "multiple": multiple nodes can be selected |
| `showNonenumerable` | `boolean` | No |  |
| `typeahead` | `boolean` | No | Whether the tree supports typeahead search |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**JsonTreeViewRootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UseTreeViewReturn<JsonNode<any>>` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**JsonTreeViewTree Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `arrow` | `ReactNode` | No | The icon to use for the arrow. |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `indentGuide` | `any` | No | The indent guide to use for the tree. |
| `renderValue` | `(node: JsonNodeHastElement) => ReactNode` | No | The function to render the value of the node. |



## Accessibility

The JSON tree view is built on top of the Tree View component and complies with the
[Tree View WAI-ARIA design pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/).


---
## link-overlay

---
title: Link Overlay
description: Used to stretch a link over a container.
panda: https://panda-css.com/docs/concepts/patterns#linkoverlay
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The link overlay pattern is used to expand a link's clickable area to its nearest
parent with `position: relative`.


```tsx



export function BasicDemo() {
  return (
    <Stack position="relative">
      <Text as="h4" textStyle="heading-sm">
        Wanna try it out?
      </Text>
      <Text color="page.text.100">
        This entire area below is a link. Hover it to see the effect.
      </Text>
      <LinkOverlay
        href="#"
        textDecoration="underline"
        _hover={{
          bgColor: 'action.bg.hover',
        }}
      >
        Click me
      </LinkOverlay>
    </Stack>
  )
}
```


## How it works

This pattern replaces the `LinkOverlay` component with a `<a>` element, allowing
the link to expand to its nearest parent and passing all props through.

### Caveat

One of the side-effects of this technique is that the content can't be "selectable"
(i.e. with a pointing device), however, this seems to be pretty uncommon in web design.

## Props

LinkOverlay accepts all CSS properties and that of an `<a>` element.


---
## loading-states

---
title: Loading States
description: Loading states are used to indicate that content is being loaded.
npm: '@cerberus-design/react'
source: 'components/spinner'
---


import {
  OverviewPreview,
} from '../components/loading-states/loading'
import {
  OverviewSpinnerPreview,
} from '../components/loading-states/spinner'
import {
  CustomSpinner,
} from '../components/loading-states/custom-spinner'

## Skeletor API

To show a skeleton loading state, simply add the `aria-busy` attribute to the element you want to show the loading state for.

```tsx
<div aria-busy="true">
  <p>This is now hidden</p>
</div>
```

}>
```tsx




export function OverviewPreview() {
  return (
    <HStack justify="space-between" w="3/4">
      <VStack alignItems="flex-start">
        <HStack justify="space-between" w="full">
          <Box aria-busy="true" rounded="sm">
            <Text>This is a description of something.</Text>
          </Box>
          <HStack>
            <Circle aria-busy="true" size="6" />
            <Circle aria-busy="true" size="6" />
            <Circle aria-busy="true" size="6" />
          </HStack>
        </HStack>
        <Box aria-busy="true" rounded="sm">
          <Text as="h2">Trash content</Text>
          <Text>
            Trash content is a place where you can find all the content that you
            have deleted. You can restore or permanently delete the content from
            here.
          </Text>
        </Box>
        <Tag
          className={css({
            alignSelf: 'center',
          })}
          shape="pill"
        >
          Skeleton
        </Tag>
      </VStack>
    </HStack>
  )
}
```


### Spinners

}>
```tsx


function MyComponent() {
  return (
    <Button>
      <Spinner size="1em" />
      Saving
    </Button>
  )
}
```


## Customization

The `Spinner` component is a simple SVG element that can be styled with CSS.

}>
```tsx


function CustomSpinner() {
  return (
    <cerberus.div
      css={{
        color: 'yellow',
        w: 20,
      }}
    >
      <Spinner />
    </cerberus.div>
  )
}
```


## API

```ts showLineNumbers=false
export type SpinnerProps = SVGProps<SVGSVGElement> & {
  size?: number | string
}

define function Spinner(props: SpinnerProps): ReactNode
```

### Props

The `Spinner` component accepts the same props as an SVG element.

| Name     | Default | Description                                                   |
| -------- | ------- | ------------------------------------------------------------- |
| size     |    | A strict `height` and `width` of the Spinner. |


---
## local-storage

---
title: 'Local Storage'
description: 'Simple helpers for managing local storage in your React applications.'
npm: '@cerberus-design/react'
source: 'utils/localStorage.ts'
---

```ts

```

## Usage

```tsx title="page.tsx"
'use client';




export default function Page() {
  const [value, setValue] = useState<string>('')

  // You have to wait until the component is mounted to
  // have access to the local storage
  useEffect(() => {
    const value = getLocalStorage('key')
    setValue(value)
  }, [])

  return (
    <Text>
      This is from local storage: {value}
    </Text>
  )
}
```

## API

### getLocalStorage

| Name     | Default | Description                                                   |
| -------- | ------- | ------------------------------------------------------------- |
| key     |    | The key that the value is saved under |
| defaultValue |    | The default value to return if the key does not exist in localStorage |


### setLocalStorage

| Name     | Default | Description                                                   |
| -------- | ------- | ------------------------------------------------------------- |
| key     |    | The key to save the value under |
| value |    | The value to save in localStorage |


---
## locale

---
title: 'Locale'
description: 'A component that sets the locale for your app, formatting dates, numbers, and other locale-specific data.'
npm: '@cerberus/react'
arkUtility: 'locale'
---

## Setup

The `LocaleProvider` component sets the locale for your app, formatting dates, numbers, and other locale-specific data.

> **Note:** If no `LocaleProvider` is setup, the default locale for the app will be `en-US` and therefore the direction
> will be `ltr`.


```tsx


export const App = () => {
  return <LocaleProvider locale="de-DE">{/* Your App */}</LocaleProvider>
}
```



## Usage

To access the current locale and direction settings, use the `useLocaleContext` hook.


```tsx


export const Usage = () => {
  const { locale, dir } = useLocaleContext()

  return <pre>{JSON.stringify({ locale, dir }, null, 2)}</pre>
}

```


## API Reference

**LocaleProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `locale` | `string` | Yes | The locale to use for the application. |


---
## marquee

---
title: Marquee
description: A marquee component that scrolls text horizontally.
npm: '@cerberus-design/react'
source: 'components/marquee'
recipe: 'slots/marquee.ts'
ark: 'marquee'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The `Marquee` is an abracted API that combines multiple primitives into a single root component.


```tsx




export function BasicDemo() {
  return (
    <Marquee spacing="5rem">
      <For each={socials}>
        {(item) => (
          <Marquee.Item key={item.label}>
            <Square size="4rem" style={{ color: item.color }}>
              <item.icon size="3rem" />
            </Square>
          </Marquee.Item>
        )}
      </For>
    </Marquee>
  )
}
```


## Spacing

Use the `spacing` prop to control the gap between content instances.


```tsx




export function SpacingDemo() {
  return (
    <Marquee spacing="2rem">
      <For each={items}>
        {(item) => (
          <Marquee.Item key={item.name}>
            <HStack
              bgColor="page.surface.100"
              borderColor="page.border.initial"
              gap="sm"
              h="5rem"
              layerStyle="outline.subtle"
              px="md"
              rounded="md"
              shadow="md"
              w="full"
            >
              {item.name} {item.logo}
            </HStack>
          </Marquee.Item>
        )}
      </For>
    </Marquee>
  )
}
```


## Reverse

Use the `reverse` prop to reverse the direction of the marquee.


```tsx




export function ReverseDemo() {
  return (
    <Marquee reverse spacing="5rem">
      <For each={socials}>
        {(item) => (
          <Marquee.Item key={item.label}>
            <Square size="4rem" style={{ color: item.color }}>
              <item.icon size="3rem" />
            </Square>
          </Marquee.Item>
        )}
      </For>
    </Marquee>
  )
}
```


## Vertical Animation

Use the `side` prop to animate the marquee vertically. The options are `top` and `bottom`.


```tsx




export function SideDemo() {
  return (
    <Marquee side="bottom" spacing="2rem" maxH="15rem" px="lg">
      <For each={items}>
        {(item) => (
          <Marquee.Item key={item.name}>
            <Center
              bgColor="page.surface.100"
              borderColor="page.border.initial"
              h="5rem"
              layerStyle="outline.subtle"
              rounded="md"
              shadow="md"
            >
              <HStack gap="sm" h="full">
                {item.name} {item.logo}
              </HStack>
            </Center>
          </Marquee.Item>
        )}
      </For>
    </Marquee>
  )
}
```


## Speed

Use the `speed` prop to control the animation speed in pixels per second.


```tsx




export function SpeedDemo() {
  return (
    <Stack gap="12" px="md" w="full">
      <For each={speeds}>
        {(speed) => (
          <Stack key={speed.value} gap="4">
            <Text textStyle="label-sm">{speed.label}</Text>
            <Marquee speed={speed.value}>
              <For each={socials}>
                {(platform) => (
                  <Marquee.Item key={platform.label} px="2rem">
                    <platform.icon color={platform.color} size="3rem" />
                  </Marquee.Item>
                )}
              </For>
            </Marquee>
          </Stack>
        )}
      </For>
    </Stack>
  )
}
```


## Edges

Use the `edges` prop to display stylized edges on the marquee. The options are `both`, `start`, and `end`.


```tsx




export function EdgesDemo() {
  return (
    <Stack gap="lg" w="full">
      <Marquee edges={['both']} spacing="5rem">
        <For each={socials}>
          {(item) => (
            <Marquee.Item key={item.label}>
              <Square size="4rem" style={{ color: item.color }}>
                <item.icon size="3rem" />
              </Square>
            </Marquee.Item>
          )}
        </For>
      </Marquee>

      <Marquee edges={['both']} side="bottom" spacing="2rem" maxH="15rem" px="lg">
        <For each={items}>
          {(item) => (
            <Marquee.Item key={item.name}>
              <Center
                bgColor="page.surface.100"
                borderColor="page.border.initial"
                h="5rem"
                layerStyle="outline.subtle"
                rounded="md"
                shadow="md"
              >
                <HStack gap="sm" h="full">
                  {item.name} {item.logo}
                </HStack>
              </Center>
            </Marquee.Item>
          )}
        </For>
      </Marquee>
    </Stack>
  )
}
```


## Pause on Interaction

Use the `pauseOnInteraction` prop to pause the marquee when users hover or focus on it, improving accessibility.


```tsx




export function PauseDemo() {
  return (
    <Marquee pauseOnInteraction spacing="5rem">
      <For each={socials}>
        {(item) => (
          <Marquee.Item key={item.label}>
            <Square size="4rem" style={{ color: item.color }}>
              <item.icon size="3rem" />
            </Square>
          </Marquee.Item>
        )}
      </For>
    </Marquee>
  )
}
```


## Context

Access the combobox's state with `ComboboxContext` or the `useComboboxContext` hook—useful for displaying the selected value or building custom UI.

<NoteAdmonition description="Since combobox is an abstracted API, you'll need to build your own to obtain the context as we do in the example below." />


```tsx
'use client'






export function StoreDemo() {
  const marquee = useMarquee({
    autoFill: true,
    spacing: '5rem',
  })

  return (
    <Stack gap="lg" w="full">
      <Marquee.RootProvider value={marquee}>
        <Marquee.Viewport>
          <Marquee.Content>
            <For each={socials}>
              {(item) => (
                <Marquee.Item key={item.label}>
                  <Square size="4rem" style={{ color: item.color }}>
                    <item.icon size="3rem" />
                  </Square>
                </Marquee.Item>
              )}
            </For>
          </Marquee.Content>
        </Marquee.Viewport>
      </Marquee.RootProvider>

      <Box ps="md">
        <Show
          when={marquee.paused}
          fallback={
            <Button onClick={marquee.pause} size="sm">
              <Pause />
              Pause
            </Button>
          }
        >
          <Button onClick={marquee.resume} size="sm" usage="outlined-subtle">
            <Play />
            Resume
          </Button>
        </Show>
      </Box>
    </Stack>
  )
}
```


## Finite Loops

To loop the marquee a finite number of times, set the `loopCount` prop on Marquee. Alternatively, use the `onLoopComplete` and `onComplete` callbacks to track the number of completed loops or when the animation fully finishes.


```tsx
'use client'






function finiteStore() {
  const [loopCount, setLoopCount] = createSignal(0)
  const [completedCount, setCompletedCount] = createSignal(0)
  return { loopCount, setLoopCount, completedCount, setCompletedCount }
}

const store = finiteStore()

export function FiniteDemo() {
  return (
    <Stack gap="lg" px="md" w="full">
      <Marquee
        loopCount={3}
        onLoopComplete={() => store.setLoopCount((prev) => prev + 1)}
        onComplete={() => store.setCompletedCount((prev) => prev + 1)}
        spacing="5rem"
      >
        <For each={socials}>
          {(item) => (
            <Marquee.Item key={item.label}>
              <Square size="4rem" style={{ color: item.color }}>
                <item.icon size="3rem" />
              </Square>
            </Marquee.Item>
          )}
        </For>
      </Marquee>

      <Stack m="4" textStyle="label-sm">
        <p>
          Loop completed: <ReactiveText data={store.loopCount} />
        </p>
        <p>
          Animation completed: <ReactiveText data={store.completedCount} />
        </p>
      </Stack>
    </Stack>
  )
}
```


## Guides

### CSS Variables

The marquee component exposes CSS variables that can be used to customize its behavior and appearance.


```tsx
// Source available in static configuration: {DEMOS.customMeta}
```


| Variable               | Description                         | Default                |
| ---------------------- | ----------------------------------- | ---------------------- |
| `--marquee-duration`   | Animation duration                  | Computed               |
| `--marquee-delay`      | Animation delay before starting     | `0s`                   |
| `--marquee-loop-count` | Number of animation iterations      | `infinite`             |
| `--marquee-edge-color` | Color for the edge gradient overlay | `page.surface.initial` |
| `--marquee-edge-size`  | Size of the edge gradient           | `20%`                  |

## Primitives

You can utilize the primitive components or the `css` prop to customize the Marquee.

| Component       | Description                                           |
| --------------- | ----------------------------------------------------- |
| MarqueeRoot     | The context provider for the Marquee family           |
| MarqueeEdge     | The stylistic edge of the Marquee                     |
| MarqueeViewport | The viewport container that holds the Marquee content |
| MarqueeContent  | The content of the Marquee                            |
| MarqueeItem     | The item to be displayed in the Marquee               |

## API

### Root Props

| Prop                 | Type                                                                              | Required | Description                                                                                                  |
| -------------------- | --------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------ |
| `asChild`            | `boolean`                                                                         | No       | Use the provided child element as the default rendered element, combining their props and behavior.          |
| `autoFill`           | `boolean`                                                                         | No       | Whether to automatically duplicate content to fill the container.                                            |
| `defaultPaused`      | `boolean`                                                                         | No       | Whether the marquee is paused by default.                                                                    |
| `delay`              | `number`                                                                          | No       | The delay before the animation starts (in seconds).                                                          |
| `ids`                | `Partial<{ root: string; viewport: string; content: (index: number) => string }>` | No       | The ids of the elements in the marquee. Useful for composition.                                              |
| `loopCount`          | `number`                                                                          | No       | The number of times to loop the animation (0 = infinite).                                                    |
| `onComplete`         | `() => void`                                                                      | No       | Function called when the marquee completes all loops and stops. Only fires for finite loops (loopCount > 0). |
| `onLoopComplete`     | `() => void`                                                                      | No       | Function called when the marquee completes one loop iteration.                                               |
| `onPauseChange`      | `(details: PauseStatusDetails) => void`                                           | No       | Function called when the pause status changes.                                                               |
| `paused`             | `boolean`                                                                         | No       | Whether the marquee is paused.                                                                               |
| `pauseOnInteraction` | `boolean`                                                                         | No       | Whether to pause the marquee on user interaction (hover, focus).                                             |
| `reverse`            | `boolean`                                                                         | No       | Whether to reverse the animation direction.                                                                  |
| `side`               | `Side`                                                                            | No       | The side/direction the marquee scrolls towards.                                                              |
| `spacing`            | `string`                                                                          | No       | The spacing between marquee items.                                                                           |
| `speed`              | `number`                                                                          | No       | The speed of the marquee animation in pixels per second.                                                     |
| `translations`       | `IntlTranslations`                                                                | No       | The localized messages to use.                                                                               |

#### Root Data Attributes:

| Attribute            | Value                          |
| -------------------- | ------------------------------ |
| `[data-scope]`       | marquee                        |
| `[data-part]`        | root                           |
| `[data-state]`       | "paused" \| "idle"             |
| `[data-orientation]` | The orientation of the marquee |
| `[data-paused]`      | Present when paused            |

#### Root CSS Variables:

| Variable               | Description                               |
| ---------------------- | ----------------------------------------- |
| `--marquee-duration`   | The marquee duration value for the Root   |
| `--marquee-spacing`    | The marquee spacing value for the Root    |
| `--marquee-delay`      | The marquee delay value for the Root      |
| `--marquee-loop-count` | The marquee loop count value for the Root |
| `--marquee-translate`  | The marquee translate value for the Root  |

### Content Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Content Data Attributes:

| Attribute            | Value                          |
| -------------------- | ------------------------------ |
| `[data-scope]`       | marquee                        |
| `[data-part]`        |                                |
| `[data-index]`       | The index of the item          |
| `[data-orientation]` | The orientation of the content |
| `[data-side]`        |                                |
| `[data-reverse]`     |                                |
| `[data-clone]`       |                                |

### Edge Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `side`    | `Side`    | Yes      | The side where the edge gradient should appear.                                                     |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Edge Data Attributes:

| Attribute            | Value                       |
| -------------------- | --------------------------- |
| `[data-scope]`       | marquee                     |
| `[data-part]`        |                             |
| `[data-side]`        |                             |
| `[data-orientation]` | The orientation of the edge |

### Item Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

### Viewport Props:

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Viewport Data Attributes:

| Attribute            | Value                           |
| -------------------- | ------------------------------- |
| `[data-scope]`       | marquee                         |
| `[data-part]`        |                                 |
| `[data-orientation]` | The orientation of the viewport |
| `[data-side]`        |                                 |

### RootProvider Props:

| Prop      | Type               | Required | Description                                                                                         |
| --------- | ------------------ | -------- | --------------------------------------------------------------------------------------------------- |
| `value`   | `UseMarqueeReturn` | Yes      |                                                                                                     |
| `asChild` | `boolean`          | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

### Parts

The `Marquee` API is an Object containing the full family of components.

| Name     | Description                                           |
| -------- | ----------------------------------------------------- |
| Root     | The context provider for the Marquee family           |
| Edge     | The stylistic edge of the Marquee                     |
| Viewport | The viewport container that holds the Marquee content |
| Content  | The content of the Marquee                            |
| Item     | The item to be displayed in the Marquee               |


---
## menu

---
title: 'Menu'
description: 'A menu component for displaying a list of options.'
npm: '@cerberus-design/react'
source: 'components/menu'
recipe: 'slots/menu.ts'
ark: 'menu'
---

import {
  NoteAdmonition
} from '@/app/components/Admonition'

import {
  BasicMenu,
  NavMenu,
  PositioningMenu,
  GroupedMenu,
  CustomMenu,
} from '../components/menu/static'

```ts
import {
  Menu,
  MenuTrigger,
  MenuContent,
  MenuItem,
  MenuItemGroup,
  MenuGroupLabel,
  MenuSeparator,
} from '@cerberus/react'
```

## Usage

}>
```tsx title="nav.tsx"
import {
  Menu,
  MenuTrigger,
  MenuContent,
  MenuItem,
  Button,
} from '@cerberus/react'


function BasicMenu() {
  return (
    <Menu>
      <MenuTrigger>
        <Button>Trigger</Button>
      </MenuTrigger>
      <MenuContent>
        <MenuItem value="item_1">
          <Strawberry />
          Item 1
        </MenuItem>
        <MenuItem value="item_2">
          <Strawberry />
          Item 2
        </MenuItem>
      </MenuContent>
    </Menu>
  )
}
```


## NextJS Usage

To create a nav menu with NextJS, you should use the `Link` component from `next/link` combined with the `asChild` prop.

}>
```tsx title="nav.tsx" /asChild/
import {
  Menu,
  MenuTrigger,
  MenuContent,
  MenuItem,
  Button,
  Logout,
} from '@cerberus/react'


function BasicMenu() {
  return (
    <Menu>
      <MenuTrigger>
        <Button>Nav Menu</Button>
      </MenuTrigger>
      <MenuContent>
        <MenuItem value="item_1" asChild>
          <Link href="/">Item 1</Link>
        </MenuItem>
        <MenuItem value="item_2" asChild>
          <Link href="/">Item 2</Link>
        </MenuItem>
        <MenuSeparator />
        <MenuItem value="item_3" asChild>
          <Link
            className={css({
              alignItems: 'center',
              colorPalette: 'danger',
              color: 'danger.text.initial',
              display: 'inline-flex',
              justifyContent: 'space-between',
              w: 'full',
            })}
            href="/"
          >
            Sign out
            <Logout />
          </Link>
        </MenuItem>
      </MenuContent>
    </Menu>
  )
}
```


## Grouped Menu

You can group menu items by using the `MenuItemGroup` component.

}>
```tsx title="nav.tsx"
import {
  Menu,
  MenuTrigger,
  MenuContent,
  MenuItem,
  MenuItemGroup,
  MenuGroupLabel,
  MenuSeparator,
  Button,
} from '@cerberus/react'

export function GroupedMenu() {
  return (
    <Menu>
      <MenuTrigger>
        <Button>Grouped Menu</Button>
      </MenuTrigger>
      <MenuContent>
        <MenuItemGroup>
          <MenuGroupLabel>Group Label</MenuGroupLabel>
          <MenuSeparator />
          <MenuItem value="item_1">Item 1</MenuItem>
          <MenuItem value="item_2">Item 2</MenuItem>
        </MenuItemGroup>
      </MenuContent>
    </Menu>
  )
}
```


## Positions

The `Menu` component accepts a `positioning` prop to determine where the menu will be positioned relative to the trigger. [See available positions](#navmenulist).

}>
```tsx title="nav.tsx" {12-14}
import {
  Menu,
  MenuTrigger,
  MenuContent,
  MenuItem,
  Button,
} from '@cerberus/react'

function BottomNav() {
  return (
    <Menu
      positioning={{
        placement: 'bottom',
      }}
    >
      <MenuTrigger>
        <Button>Bottom</Button>
      </MenuTrigger>
      <MenuContent>
        <MenuItem value="item_1">Item 1</MenuItem>
        <MenuItem value="item_2">Item 2</MenuItem>
      </MenuContent>
    </Menu>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the menu.

| Component | Description |
| --------- | ----------- |
| MenuRoot    | The context provider for the menu parts |
| MenuTrigger  | The trigger that opens the menu content |
| MenuTriggerItem  | The item that triggers a nested menu content |
| MenuIndicator  | The indicator for the selected menu item |
| MenuPositioner  | The positioning container for the menu content |
| MenuContent  | The content of the menu |
| MenuItem  | A single item of the menu |
| MenuItemGroup  | A container for a group of menu items |
| MenuItemGroupLabel  | The label for a group of menu items |
| MenuSeparator  | A separator between menu items |


}>
```tsx title=Menu custom demo"
import {
  Menu,
  MenuTrigger,
  MenuContent,
  MenuItem,
  Button,
} from '@cerberus/react'

function CustomMenu() {
  return (
    <Menu>
      <MenuTrigger>
        <Button
          css={{
            color: 'black',
          }}
          palette="danger"
        >
          Hades R00lz
        </Button>
      </MenuTrigger>
      <MenuContent
        css={{
          bgColor: 'black',
          color: 'danger.text.initial',
        }}
      >
        <MenuItem
          css={{
            colorPalette: 'warning',
            _hover: {
              color: 'black',
            },
          }}
          value="item_1"
        >
          Hades am I
        </MenuItem>
        <MenuItem
          css={{
            colorPalette: 'warning',
            _hover: {
              color: 'black',
            },
          }}
          value="item_2"
        >
          Hades is also where I live
        </MenuItem>
      </MenuContent>
    </Menu>
  )
}
```


## API

### Menu

```ts showLineNumbers=false
export interface MenuProps {
  positioning?: {
    placement: 'left' | 'right' | 'top' | 'bottom'
  }
}
```

| Name     | Default    |       Description                                   |
| -------- | ------- | ------------------------------------------------------ |
| positioning     | null   | Used to position the menu content.  |


### MenuTrigger

```ts showLineNumbers=false
export interface MenuTriggerProps {
  children: React.ReactNode
}
```

| Name     | Default    |       Description                                   |
| -------- | ------- | ------------------------------------------------------ |
| children     | null   | The trigger element.  |

### MenuItem

```ts showLineNumbers=false
export interface MenuItemProps {
  children: React.ReactNode
  value: string
  asChild?: boolean
}
```

| Name     | Default    |       Description                                   |
| -------- | ------- | ------------------------------------------------------ |
| children     | null   | The content of the menu item.  |
| value     | null   | The value of the menu item used for selection.  |
| asChild     | false   | Used to render the children as a child component.  |


---
## notifications

---
title: Notifications
description: The Notification component is used to display notifications in your application.
npm: '@cerberus-design/react'
source: 'components/notifications'
recipe: 'slots/toast.ts'
ark: 'toast'
---



import {
  CustomConfigDemo,
  OverviewDemo,
  SubtleDemo,
} from '../components/notifications/static'


```ts

```

## Usage

The `NotificationCenter` component is used to manage notifications in your application. It works together with the `toaster` object to display notifications.

}>
```tsx title="Basic demo" {7-17}
'use client';



function Feature() {
const handleClick = useCallback(() => {
toaster.create({
type: 'info',
title: 'Update Available',
description: 'A new version of the app is available',
action: {
label: 'Refresh',
onClick: () => {
window.location.reload()
}
}
})
}, [])

return <Button onClick={handleClick}>Trigger notification</Button>
}

````
```tsx title="layout.tsx"


export function Layout(props: PropsWithChildren<{}>) {
  return (
    <>
      {props.children}
      <NotificationCenter />
    </>
  )
}
````



### Types

Just update the `options.types` to change the theme of the notification. The options are `info`, `success`, `warning`, `danger`, and `loading`.

}>
```tsx title="Types demo" {8}
'use client';



function Feature() {
const handleClick = useCallback(() => {
toaster.create({
type: 'loading',
title: 'Loading',
description: 'It's taking longer than normal.',
})
}, [toaster.create])

return <Button onClick={handleClick}>Trigger notification</Button>
}

````


## Subtle Notifications

Subtle notifications are a less intrusive way to inform users about events or updates. They typically have a softer appearance and may not require immediate user action.

Use the `usage: 'subtle'` option to create a subtle notification.

}>
```tsx title="Subtle Notifications Demo"
'use client';



function Feature() {
  const handleClick = useCallback(() => {
    toaster.create({
      type: 'info',
      usage: 'subtle',
      title: 'Update Available',
      description: 'A new version of the app is available',
      action: {
        label: 'Refresh',
        onClick: () => {
          window.location.reload()
        }
      }
    })
  }, [])

  return <Button onClick={handleClick}>Trigger subtle notification</Button>
}
````



## Custom Configuration

You can customize the notification behavior by calling the `createToaster` function. This allows you to create a new toaster instance with your desired configuration.

We recommend scoping this to a component to ensure Next.js rehydration works correctly.

}>
```tsx title="Custom Configuration" /createToaster/
'use client';




function CustomConfigDemo() {
const customToaster = createToaster({
gap: 24,
overlap: false,
placement: 'bottom-end',
})

return (

<>
<HStack>
<Button
onClick={() => {
customToaster.create({
title: 'Custom Toaster',
description:
'This notification is using a custom toaster configuration.',
type: 'success',
})
}} >
Show Notification
</Button>
</HStack>

      <NotificationCenter toaster={customToaster} />
    </>

)
}

````


## Badges

Badges can be used to show the number of notifications on any trigger by using the `data-notify` and `data-notify-count` attributes.

> **Note:** Combine this with the `formatNotifyCount` helper that will restrict the count to 3 digits.

}>
```tsx title="some-page.tsx" {8-9}



export function NotifyBadgePreview() {
  return (
    <IconButton
      ariaLabel="View notifications"
      data-notify
      data-notify-count={formatNotifyCount(100)}
    >
    <Notifications />
  </IconButton>
  )
}
````



## Primitives

You can utilize the primitive components to customize the toast notification.

| Component                 | Description                                       |
| ------------------------- | ------------------------------------------------- |
| NotificationProvider      | The context provider for the toast notifications. |
| NotificationRoot          | The context provider for the toast parts.         |
| NotificationHeading       | The title heading of the toast.                   |
| NotificationDescription   | The description of the toast.                     |
| NotificationCloseTrigger  | The close button of the toast.                    |
| NotificationActionTrigger | The action button of the toast.                   |

## API

### Props

The `NotificationCenter` component is an abstraction of the primitives and doesn't accept any props.

### `toaster`

The `toaster` object is used to create notifications and accepts the following options:

| Name        | Type                    | Description                                                                                 |
| ----------- | ----------------------- | ------------------------------------------------------------------------------------------- |
| type        | string                  | The type of notification. Options are `info`, `success`, `warning`, `error`, and `loading`. |
| title       | string                  | The title of the notification.                                                              |
| description | string                  | The description of the notification.                                                        |
| action      | `ToasterAction`         | The action object of the notification.                                                      |
| duration    | number                  | A custom duration of the notification.                                                      |
| onClose     | function                | The callback function when the notification is closed.                                      |
| usage       | `'subtle' \| 'default'` | The visual type of the notification. The default option is `default`.                       |

### `ToasterAction`

The `ToasterAction` object is used to create an action button for the notification and accepts the following options:

| Name    | Type     | Description                                              |
| ------- | -------- | -------------------------------------------------------- |
| label   | string   | The label of the action button.                          |
| onClick | function | The callback function when the action button is clicked. |

### Parts

The `NotificationParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the NotificationParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name          | Description                                                                               |
| ------------- | ----------------------------------------------------------------------------------------- |
| Root          | The `NotificationRoot` component which is the Provider for the toast.                     |
| Heading       | The `NotificationHeading` component which displays the heading title for the toast.       |
| Description   | The `NotificationDescription` component which displays the description for the toast.     |
| CloseTrigger  | The `NotificationCloseTrigger` component which displays the close button for the toast.   |
| ActionTrigger | The `NotificationActionTrigger` component which displays the action button for the toast. |


---
## number-input

---
title: Number Input
description: The Number Input component is used to manage numeric input fields.
npm: '@cerberus-design/react'
source: 'components/number-input'
recipe: 'slots/numberInput.ts'
ark: 'number-input'
---






```ts

```

## Usage

The `NumberInput` component provides a way to create input fields specifically for numeric values. It includes features such as increment and decrement buttons, and can be easily integrated with form libraries.

}>
```tsx



export function NumberInputDemo() {
  return (
    <Box w="1/2">
      <Field label="How many?" helperText="Choose your quantity.">
        <NumberInput />
      </Field>
    </Box>
  )
}
```


## Scrubber

The NumberInput supports the scrubber interaction pattern. To use this pattern, use the `scrubber` prop. It uses the Pointer lock API and tracks the pointer movement. It also renders a virtual cursor which mimics the real cursor's pointer

}>
```tsx /scrubber/



export function ScrubberDemo() {
  return (
    <Box w="1/2">
      <Field
        label="How many?"
        helperText="Use your mouse wheel to change the value."
      >
        <NumberInput scrubber />
      </Field>
    </Box>
  )
}
```


## Sizes

The `NumberInput` component supports different sizes to accommodate various design requirements. You can specify the size using the `size` prop.

}>
```tsx



export function SizesDemo() {
  return (
    <HStack w="3/4">
      <Field label="Small size">
        <NumberInput size="sm" />
      </Field>
      <Field label="Medium size">
        <NumberInput size="md" />
      </Field>
      <Field label="Large size">
        <NumberInput size="lg" />
      </Field>
    </HStack>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the number input.

| Component | Description |
| --------- | ----------- |
| NumberInputRoot    | The context provider for the NumberInput parts |
| NumberInputLabel   | The label of the NumberInput |
| NumberInputControl | The wrapper of the NumberInput contents |
| NumberInputInput   | The input of the NumberInput |
| NumberInputIncrementTrigger | The increment button of the NumberInput |
| NumberInputDecrementTrigger | The decrement button of the NumberInput |
| NumberInputScrubber | The scrubber of the NumberInput |

}>
```tsx




export function CustomDemo() {
  return (
    <HStack w="1/2">
      <NumberInputParts.Root
        css={{
          display: 'flex',
          w: 'full',
        }}
      >
        <NumberInputParts.Label
          css={{
            textStyle: 'heading-xs',
          }}
        >
          This is custom
        </NumberInputParts.Label>

        <NumberInputParts.Control>
          <NumberInputParts.Input />
          <NumberInputParts.IncrementTrigger
            css={{
              bgColor: 'success.surface.initial',
              color: 'success.text.initial',
            }}
          >
            <Add />
          </NumberInputParts.IncrementTrigger>
          <NumberInputParts.DecrementTrigger
            css={{
              bgColor: 'danger.surface.initial',
              color: 'danger.text.inverse',
            }}
          >
            <Subtract />
          </NumberInputParts.DecrementTrigger>
          <NumberInputParts.Scrubber />
        </NumberInputParts.Control>
      </NumberInputParts.Root>
    </HStack>
  )

```



## API

### Props

The `NumberInput` component is an abstraction of the primitives and accepts the following props:

| Name     | Default | Description                                            |
| -------- | ------- | ------------------------------------------------------ |
| scrubber | false   | Use scrubber controls for the number input.            |


The `NumberInput` component also accepts all the props of the [`NumberInputRoot` primitive props](https://ark-ui.com/react/docs/components/number-input#api-reference)

### Parts

The `NumberInputParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the NumberInputParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name     | Description                            |
| -------- | -------------------------------------- |
| Root     | The `NumberInputRoot` component which is the Provider for the family. |
| Label    | The `NumberInputLabel` component which displays the label and "required" notice. |
| Input     | The `NumberInputInput` component which is the input field. |
| Control   | The `NumberInputControl` component which is the wrapper for the input and buttons. |
| IncrementTrigger | The `NumberInputIncrementTrigger` component which is the increment button. |
| DecrementTrigger | The `NumberInputDecrementTrigger` component which is the decrement button. |
| Scrubber  | The `NumberInputScrubber` component which is the scrubber control. |


---
## overview

---
title: Components
description: Accessible and easy to use or customize UI components
---



## Categories

Here are a list of the components available in this library, grouped by their functionality:

<CategoryList group="actions" />
<CategoryList group="communication" />
<CategoryList group="containment" />
<CategoryList group="navigation" />
<CategoryList group="selection" />
<CategoryList group="inputs" />


---
## pagination

---
title: Pagination
description: A navigation component that allows users to browse through pages.
npm: '@cerberus-design/react'
source: 'components/pagination'
ark: 'pagination'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

Used to navigate through a series of pages.


```tsx


export function BasicDemo() {
  return <Pagination count={5000} pageSize={10} siblingCount={2} />
}
```


## Attached

To change the layout style of the pagination, you can use the `layout` prop from the 
`Group` component.


```tsx


export function AttachedDemo() {
  return (
    <Pagination count={20} pageSize={2} defaultPage={1} layout="attached" />
  )
}
```


## Compact

To show a compact pagination style, use the `compact` prop. This can be useful for mobile.


```tsx


export function CompactDemo() {
  return <Pagination compact count={5000} pageSize={10} siblingCount={2} />
}
```


## Data Slicing

Use the `slice()` method to paginate actual data arrays. This method automatically 
slices your data based on the current page and page size.


```tsx
'use client'

import {
  Group,
  Pagination,
  Text,
  usePaginationContext,
} from '@cerberus-design/react'



export function SliceDemo() {
  return (
    <VStack textAlign="center" w="3/4">
      <Pagination count={users.length} pageSize={5}>
        <UserList />
      </Pagination>
    </VStack>
  )
}

function UserList() {
  const pagination = usePaginationContext()
  return (
    <Group orientation="vertical" pb="lg" w="full">
      {pagination.slice(users).map((user) => (
        <HStack
          key={user.id}
          bgColor="page.bg.100"
          gap="md"
          p="md"
          rounded="sm"
          w="full"
        >
          <Text color="page.text.initial" textStyle="body-md">
            {user.name}
          </Text>
          <Text as="small" color="page.text.100" textStyle="label-sm">
            {user.email}
          </Text>
        </HStack>
      ))}
    </Group>
  )
}
```


## Alignment

To align the pagination items, use the alignment props on a parent element. This 
will be differentdepending on the layout.


```tsx




export function AlignmentDemo() {
  return (
    <VStack alignItems="flex-end" w="3/4">
      <DecorativeBox h="200px" />
      <Pagination count={5} pageSize={2} />
    </VStack>
  )
}
```


## Controlled

Use the `onPageChange` prop to control the active page of the pagination.


```tsx
'use client'




export function ControlledDemo() {
  const [currentPage, setCurrentPage] = useState<number>(1)

  return (
    <Pagination
      count={5000}
      onPageChange={(details) => setCurrentPage(details.page)}
      page={currentPage}
      pageSize={10}
      siblingCount={2}
    />
  )
}
```


## Page Size

Control the number of items per page dynamically using `setPageSize()`. This example 
shows how to integrate a native select element to change the page size.

> **Note:**  For uncontrolled behavior, use defaultPageSize to set the initial value. For controlled behavior, use pageSize and onPageSizeChange to programmatically manage the page size.


```tsx
'use client'

import {
  createSelectCollection,
  Field,
  For,
  Group,
  Option,
  Pagination,
  Select,
  type SelectValueChangeDetails,
  Text,
  usePaginationContext,
} from '@cerberus-design/react'



export function PageDemo() {
  return (
    <VStack textAlign="center" w="3/4">
      <Pagination count={20} defaultPageSize={2}>
        <HStack justify="flex-end" pb="md" w="full">
          <PageSize />
        </HStack>

        <UserList />
      </Pagination>
    </VStack>
  )
}

function PageSize() {
  const pagination = usePaginationContext()
  const collection = createSelectCollection([
    { label: '2', value: '2' },
    { label: '4', value: '4' },
    { label: '6', value: '6' },
    { label: '8', value: '8' },
    { label: '10', value: '10' },
  ])

  return (
    <HStack justify="flex-end" w="full">
      <Text as="small" color="page.text.100" textStyle="label-sm">
        Items per page:
      </Text>

      <Field label="Select page size" hideLabel w="initial">
        <Select
          collection={collection}
          onValueChange={(details: SelectValueChangeDetails) =>
            pagination.setPageSize(Number(details.value))
          }
          value={[String(pagination.pageSize)]}
          w="fit-content"
        >
          <For each={collection.items}>
            {(item) => <Option key={item.value} item={item} />}
          </For>
        </Select>
      </Field>
    </HStack>
  )
}

function UserList() {
  const pagination = usePaginationContext()
  return (
    <Group orientation="vertical" pb="lg" w="full">
      {pagination.slice(users).map((user) => (
        <HStack
          key={user.id}
          bgColor="page.bg.100"
          gap="md"
          p="md"
          rounded="sm"
          w="full"
        >
          <Text color="page.text.initial" textStyle="body-md">
            {user.name}
          </Text>
          <Text as="small" color="page.text.100" textStyle="label-sm">
            {user.email}
          </Text>
        </HStack>
      ))}
    </Group>
  )
}
```


## Customization

You can utilize the `css` prop to customize the pagination by selecting the desired
prmitive `data-scope` layers.


```tsx
'use client'

import {
  ItemList,
  PaginationParts,
  Text,
  type PaginationContextDetails,
} from '@cerberus-design/react'


export function CustomDemo() {
  return (
    <PaginationParts.Root count={1000} pageSize={10} asChild>
      <HStack bgColor="page.bg.100" justify="space-between" p="md" w="full">
        <PaginationParts.Context>
          {(pagination: PaginationContextDetails) => (
            <>
              <Text as="small" textStyle="label-sm">
                {pagination.page} of {pagination.totalPages}
              </Text>

              <ItemList {...pagination} />
            </>
          )}
        </PaginationParts.Context>
      </HStack>
    </PaginationParts.Root>
  )
}
```


## API

### Primitives

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `count` | `number` | No | Total number of data items |
| `defaultPage` | `number` | No | The initial active page when rendered.
Use when you don't need to control the active page of the pagination. |
| `defaultPageSize` | `number` | No | The initial number of data items per page when rendered. Use when you don't need to control the page size of the pagination. |
| `getPageUrl` | `(details: PageUrlDetails) => string` | No | Function to generate href attributes for pagination links. Only used when `type` is set to "link". |
| `ids` | `Partial<PrimitiveLayers>` | No | The ids of the elements in the accordion. Useful for composition. |
| `onPageChange` | `(details: PageChangeDetails) => void` | No | Called when the page number is changed |
| `onPageSizeChange` | `(details: PageSizeChangeDetails) => void` | No | Called when the page size is changed |
| `page` | `number` | No | The controlled active page |
| `pageSize` | `number` | No | The controlled number of data items per page |
| `siblingCount` | `number` | No | Number of pages to show beside active page |
| `translations` | `IntlTranslations` | No | Specifies the localized strings that identifies the accessibility elements and their states |
| `type` | `'button', 'link'` | No | The type of the trigger element |


**Ellipsis Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `index` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `type` | `'page'` | Yes |  |
| `value` | `number` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Item Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | pagination |
| `[data-part]` | item |
| `[data-index]` | The index of the item |
| `[data-selected]` | Present when selected |


**NextTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**NextTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | pagination |
| `[data-part]` | next-trigger |
| `[data-disabled]` | Present when disabled |


**PrevTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**PrevTrigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | pagination |
| `[data-part]` | prev-trigger |
| `[data-disabled]` | Present when disabled |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UsePaginationReturn` | Yes |  |
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


---
## pin-input

---
title: Pin Input
description: Enter and manage secure multi-character codes with the PinInput component.
npm: '@cerberus-design/react'
source: 'components/pin-input'
recipe: 'slots/pin-input.ts'
ark: 'pin-input'
---





```ts

```

## Usage

The PinInput component lets users enter fixed-length codes (such as verification codes or PINs) one character at a time. It manages focus movement between inputs and aggregates the value for you.

}>
```tsx



export function StaticPreview() {
  return (
    <HStack w="1/2">
      <Field label="Enter PIN">
        <PinInput />
      </Field>
    </HStack>
  )
}
```


## Blur on complete

By default, the last input maintains focus when filled, and we invoke the `onValueComplete` callback. To blur the last input when the user completes the input, set the prop `blurOnComplete` to true.

}>
```tsx



export function StaticPreview() {
  return (
    <HStack w="1/2">
      <PinInput blurOnComplete />
    </HStack>
  )
}
```


## Count

The `count` prop determines the number of individual input boxes rendered. This is useful for specifying the length of the PIN or code the user needs to enter.

}>
```tsx /count/



export function CountPreview() {
  return (
    <HStack w="1/2">
      <Field label="5 Digits">
        <PinInput placeholder={undefined} count={5} />
      </Field>
    </HStack>
  )
}
```


## Sizes

The PinInput component supports different sizes to accommodate various design requirements.

}>
```tsx



export function SizesPreview() {
  return (
    <HStack w="1/2">
      <Field label="Medium">
        <PinInput size="md" />
      </Field>
      <Field label="Large">
        <PinInput size="lg" />
      </Field>
    </HStack>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the PinInput component.

| Component              | Description                                      |
| ---------------------- | ------------------------------------------------ |
| PinInputRoot           | Root context provider for the family.            |
| PinInputLabel          | Accessible label element.                        |
| PinInputControl        | Wraps the individual input boxes.                |
| PinInputInput          | A single character input field.                  |
| PinInputHiddenInput    | Aggregated hidden input used in forms.           |

}>

```tsx



function CustomPreview() {
  return (
    <HStack w="1/2">
      <PinInputParts.Root
        css={{
          w: 'full',
        }}
      >
        <PinInputParts.Control
          css={{
            transform: 'translateX(-4px)',
          }}
        >
          {Array.from({ length: 4 }, (_, index) => (
            <PinInputParts.Input
              key={index}
              index={index}
              css={{
                border: '2px solid',
                borderColor: 'black',
                borderRadius: 'md',
                h: '24',
                w: '24',
                textAlign: 'center',
                fontSize: 'lg',
                lineHeight: '12',
                '&:focus': {
                  borderColor: 'danger.bg.initial',
                  boxShadow: '0 0 0 3px rgba(255, 69, 58, 0.6)',
                },
              }}
            />
          ))}
        </PinInputParts.Control>
        <PinInputParts.HiddenInput />
      </PinInputParts.Root>
    </HStack>
  )
}
```



## API

### PinInput

The `PinInput` component is an abstraction over the primitive parts and exposes all Ark UI **Root** props. Below is a reference table for convenience (see the [Ark UI Pin Input API](https://ark-ui.com/docs/components/pin-input#api-reference) for authoritative details).

| Name | Default | Description |
| ---- | ------- | ----------- |
| asChild |  | Use the provided child element as the rendered element. |
| autoFocus |  | Auto‑focus the first input on mount. |
| blurOnComplete |  | Blur the last input when the value becomes complete. |
| count |  | Number of inputs to render (improves SSR a11y; will become required in next major). |
| defaultValue |  | Uncontrolled initial value array (e.g. `['1','2','3']`). |
| disabled |  | Disable the entire pin input. |
| dir | `ltr` | Text direction; affects arrow key navigation. |
| form |  | Id of an external form to associate the hidden input with. |
| id |  | Base id used to derive ids for parts. |
| ids |  | Object of element id overrides for composition. |
| invalid |  | Mark the pin input as invalid. Adds `data-invalid`. |
| mask |  | Mask each input character similar to a password field. |
| name |  | Name attribute for the hidden input (form submission). |
| onValueChange |  | Fired whenever any input value changes. Provides `{ value, valueAsString }`. |
| onValueComplete |  | Fired when all inputs have valid values (typing or paste). |
| onValueInvalid |  | Fired when an invalid value is entered (fails `type` or `pattern`). |
| otp |  | Enables one‑time‑code autocomplete optimizations (`autocomplete="one-time-code"`). |
| pattern |  | Regular expression the characters must satisfy. |
| placeholder | `"○"` | Placeholder character shown in empty inputs. |
| readOnly |  | Make inputs read‑only. |
| required |  | Mark the inputs as required. |
| selectOnFocus |  | Select the existing character when an input gains focus. |
| translations |  | Localized strings for accessibility / messages. |
| type | `"numeric"` | Allowed character set: `numeric`, `alphabetic`, or `alphanumeric`. |
| value |  | Controlled value array (set length to number of inputs). |

The `PinInput` component also accepts standard DOM props for the root element and mirrors the Ark UI Root behavior.

The PinInput is an abstraction of the underlying Ark UI primitive [Root component](https://ark-ui.com/react/docs/components/pin-input).

### Parts

The `PinInputParts` API is an object containing the full family of components.

> **Note:** It is best to only use the PinInputParts if you are building a custom solution. Importing object-based components can increase bundle size because every part is included.

| Name | Description |
| ---- | ----------- |
| Root | The `PinInputRoot` component which is the provider for the family. |
| Label | The `PinInputLabel` component. |
| Control | The `PinInputControl` layout wrapper. |
| Input | The `PinInputInput` component. |
| HiddenInput | The `PinInputHiddenInput` component. |


---
## popover

---
title: Popover
description: Used to show detailed information inside a pop-up.
npm: '@cerberus-design/react'
source: 'components/popover'
recipe: 'slots/popover.ts'
ark: 'popover'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The `Popover` component is a controlled abstraction of the primitive parts that can be used to show or hide content.


```tsx
'use client'




export function BasicDemo() {
  return (
    <Popover trigger={<Button>Trigger</Button>}>
      <HStack p="md" w="full">
        Everything is content...
      </HStack>
    </Popover>
  )
}
```


## Helper Slots

For advanced layouts, you can utilize the helper slots to streamline styling. Layout related slots correspond to the `size` variant provided.


```tsx
'use client'





export function SlotsDemo() {
  return (
    <Popover trigger={<Button>Trigger</Button>} size="lg">
      <Popover.Header>
        <HStack gap="md" pb="lg" w="full">
          <Box pos="relative">
            <Avatar fallback={<AiAgentInvocation />} gradient="asphodel-dark" />
            <Float placement="bottom-end" offsetX="1" offsetY="1">
              <Circle
                bgColor="success.bg.active"
                outline="0.2em solid"
                outlineColor="page.surface.initial"
                size="8px"
              />
            </Float>
          </Box>

          <Stack direction="column" gap="xs">
            <Popover.Title textStyle="heading-xs">Cerby tha Dawg</Popover.Title>
            <Popover.Description as="small" color="page.text.100" textStyle="body-xs">
              The best boi there is
            </Popover.Description>
          </Stack>
        </HStack>
      </Popover.Header>

      <Divider color="page.border.initial" thickness="1px" />

      <Popover.Body>
        <HStack color="page.text.100" gap="sm" w="full">
          <Time />
          <Text color="page.text.initial">6:66 Local Time</Text>
        </HStack>
      </Popover.Body>

      <Popover.Footer>
        <ButtonGroup>
          <Button size="sm" usage="outlined-subtle">
            <Chat />
            Message
          </Button>
          <Button size="sm" usage="outlined-subtle">
            <UserFollow />
            Add
          </Button>
        </ButtonGroup>
      </Popover.Footer>
    </Popover>
  )
}
```


### Slots

The following slots are available on the `Popover` object:

| Component     | Description                                    |
| ------------- | ---------------------------------------------- |
| `Header`      | Useful for controlling header block styles.    |
| `Body`        | Useful for controlling "body" block styles.    |
| `Footer`      | Useful for controlling footer block styles.    |
| `Title`       | Useful for controlling heading-related styles. |
| `Description` | Useful for controlling body-related styles.    |

## Sizes

The `Popover` component supports sizes: `xs` to `lg`. This changes the padding of the layout slots.


```tsx
Example not found
```


## Arrow

Set the `usage` prop to `arrow` to show an arrow tip.


```tsx
'use client'




export function ArrowDemo() {
  return (
    <Popover trigger={<Button>Trigger</Button>} usage="arrow">
      <HStack p="md" w="full">
        Everything is content...
      </HStack>
    </Popover>
  )
}
```


## Positioning

Use the `positioning.placement` prop to configure the underlying `floating-ui` positioning logic.


```tsx
'use client'



export function PlacementDemo() {
  return (
    <Popover
      trigger={<Button>Trigger</Button>}
      positioning={{
        placement: 'left-start',
        offset: { mainAxis: 12, crossAxis: 12 },
      }}
    >
      <Popover.Body>Everything is content...</Popover.Body>
    </Popover>
  )
}
```


## Lazy Mounting

Use the `lazyMounted` and/or `unmountOnExit` prop to defer the mounting of the popover content until it's opened.


```tsx
'use client'



export function LazyDemo() {
  return (
    <Popover trigger={<Button>Trigger</Button>} lazyMounted unmountOnExit>
      <Popover.Body>Everything is content...</Popover.Body>
    </Popover>
  )
}
```


## Nesting

Popovers can be nested within each other. Each nested popover maintains its own open state and positioning.


```tsx
'use client'



export function NestedDemo() {
  return (
    <Popover trigger={<Button>Trigger</Button>}>
      <Popover.Body>
        This is the parent popover content.
        <Popover
          trigger={
            <Button usage="outlined-subtle" size="sm">
              Trigger
            </Button>
          }
        >
          <Popover.Body>This is the nested popover content.</Popover.Body>
        </Popover>
      </Popover.Body>
    </Popover>
  )
}
```


## Anchor

Use `PopoverParts.Anchor` to position the popover relative to a different element than the trigger.

> **Note:** Anchor positioning requires the use of PopoverParts since there needs to be an entire layout adjustment.


```tsx
'use client'




export function AnchorDemo() {
  return (
    <PopoverParts.Root size="lg">
      <HStack gap="md">
        <PopoverParts.Trigger asChild>
          <Button size="sm" usage="outlined-subtle">
            Trigger
          </Button>
        </PopoverParts.Trigger>

        <PopoverParts.Anchor>
          <Input placeholder="Anchor..." size="sm" />
        </PopoverParts.Anchor>
      </HStack>

      <PopoverParts.Positioner>
        <PopoverParts.Content>
          <PopoverParts.Body>This is anchored to the input.</PopoverParts.Body>
        </PopoverParts.Content>
      </PopoverParts.Positioner>
    </PopoverParts.Root>
  )
}
```


## Customizing

You can customize the `Popover` using style props and data selectors on any slot primitve.


```tsx
'use client'



export function CustomDemo() {
  return (
    <PopoverParts.Root size="lg">
      <PopoverParts.Trigger>Custom Trigger</PopoverParts.Trigger>

      <PopoverParts.Positioner>
        <PopoverParts.Content bgColor="page.bg.100" border="2px solid" rounded="none">
          <PopoverParts.Header pb="lg">This is a custom popover</PopoverParts.Header>
          <PopoverParts.Body bgColor="page.bg.200">
            That is fully built from scratch
          </PopoverParts.Body>
          <PopoverParts.Footer textStyle="heading-2xs">
            Footer sturf
          </PopoverParts.Footer>
        </PopoverParts.Content>
      </PopoverParts.Positioner>
    </PopoverParts.Root>
  )
}
```


## Guides

### Available Size

The following css variables are exposed to the `PopoverPositioner` which you can use to style the `PopoverContent`

<CodeSnippet
  snippet={`// width of the popover trigger
--reference-width: <pixel-value>;
// width of the available viewport
--available-width: <pixel-value>;
// height of the available viewpor
--available-height: <pixel-value>;`}
/>

For example, if you want to make sure the maximum height doesn't exceed the available height, use the following css:


```tsx
// Source available in static configuration: {DEMOS.dataSelector}
```


## Primitives

The layers of the `Popover` which can be used to create a fully custom solution.

| Component           | Description                                        |
| ------------------- | -------------------------------------------------- |
| PopoverRoot         | The main container for the popover.                |
| PopoverTrigger      | The trigger that toggles the popover content.      |
| PopoverAnchor       | The container to anchor the popover content to.    |
| PopoverPositioner   | The positioning container for the popover content. |
| PopoverArrow        | The arrow container.                               |
| PopoverArrowTip     | The actual visible arrow.                          |
| PopoverContent      | The content container.                             |
| PopoverTitle        | The heading for a popover.                         |
| PopoverDescription  | The description for a popover.                     |
| PopoverCloseTrigger | The close trigger for a popover.                   |
| PopoverHeader       | The header for a popover.                          |
| PopoverBody         | The body for a popover.                            |
| PopoverFooter       | The footer for a popover.                          |

### Data Attributes

The primitives additionally use the following data attributes for custom styling:

| Name         | Value         | Description                         |
| ------------ | ------------- | ----------------------------------- |
| `data-scope` | `popover`     | The scope of the components.        |
| `data-part`  | `root`        | The root layer of the scope.        |
| `data-part`  | `trigger`     | The trigger layer of the scope.     |
| `data-part`  | `anchor`      | The anchor layer of the scope.      |
| `data-part`  | `anchor-tip`  | The anchor-tip layer of the scope.  |
| `data-part`  | `positioner`  | The positioner layer of the scope.  |
| `data-part`  | `arrow`       | The arrow layer of the scope.       |
| `data-part`  | `arrow-tip`   | The arrow-tip layer of the scope.   |
| `data-part`  | `content`     | The content layer of the scope.     |
| `data-part`  | `title`       | The title layer of the scope.       |
| `data-part`  | `description` | The description layer of the scope. |
| `data-part`  | `header`      | The header layer of the scope.      |
| `data-part`  | `body`        | The body layer of the scope.        |
| `data-part`  | `footer`      | The footer layer of the scope.      |

## API

### Root Props

| Prop                     | Type                                       | Required | Description                                                                                                                                                                                                                   |
| ------------------------ | ------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `autoFocus`              | `boolean`                                  | No       | Whether to automatically set focus on the first focusable content within the popover when opened.                                                                                                                             |
| `closeOnEscape`          | `boolean`                                  | No       | Whether to close the popover when the escape key is pressed.                                                                                                                                                                  |
| `closeOnInteractOutside` | `boolean`                                  | No       | Whether to close the popover when the user clicks outside of the popover.                                                                                                                                                     |
| `defaultOpen`            | `boolean`                                  | No       | The initial open state of the popover when rendered. Use when you don't need to control the open state of the popover.                                                                                                        |
| `id`                     | `string`                                   | No       | The unique identifier of the machine.                                                                                                                                                                                         |
| `ids`                    | `Partial<PrimitiveSlots>`                  | No       | The ids of the elements in the popover. Useful for composition.                                                                                                                                                               |
| `immediate`              | `boolean`                                  | No       | Whether to synchronize the present change immediately or defer it to the next frame                                                                                                                                           |
| `initialFocusEl`         | `() => HTMLElement \| null`                | No       | The element to focus on when the popover is opened.                                                                                                                                                                           |
| `lazyMount`              | `boolean`                                  | No       | Whether to enable lazy mounting                                                                                                                                                                                               |
| `modal`                  | `boolean`                                  | No       | Whether the popover should be modal. When set to`true`: interaction with outside elements will be disabled, only popover content will be visible to screen readers, scrolling is blocked, focus is trapped within the popover |
| `onEscapeKeyDown`        | `(event: KeyboardEvent) => void`           | No       | Function called when the escape key is pressed                                                                                                                                                                                |
| `onExitComplete`         | `VoidFunction`                             | No       | Function called when the animation ends in the closed state                                                                                                                                                                   |
| `onFocusOutside`         | `(event: FocusOutsideEvent) => void`       | No       | Function called when the focus is moved outside the component                                                                                                                                                                 |
| `onInteractOutside`      | `(event: InteractOutsideEvent) => void`    | No       | Function called when an interaction happens outside the component                                                                                                                                                             |
| `onOpenChange`           | `(details: OpenChangeDetails) => void`     | No       | Function invoked when the popover opens or closes                                                                                                                                                                             |
| `onPointerDownOutside`   | `(event: PointerDownOutsideEvent) => void` | No       | Function called when the pointer is pressed down outside the component                                                                                                                                                        |
| `onRequestDismiss`       | `(event: LayerDismissEvent) => void`       | No       | Function called when this layer is closed due to a parent layer being closed                                                                                                                                                  |
| `open`                   | `boolean`                                  | No       | The controlled open state of the popover                                                                                                                                                                                      |
| `persistentElements`     | `(() => Element \| null)[]`                | No       | Returns the persistent elements that: should not have pointer-events disabled, should not trigger the dismiss event                                                                                                           |
| `portalled`              | `boolean`                                  | No       | Whether the popover is portalled. This will proxy the tabbing behavior regardless of the DOM position of the popover content.                                                                                                 |
| `positioning`            | `PositioningOptions`                       | No       | The user provided options used to position the popover content                                                                                                                                                                |
| `present`                | `boolean`                                  | No       | Whether the node is present (controlled by the user)                                                                                                                                                                          |
| `skipAnimationOnMount`   | `boolean`                                  | No       | Whether to allow the initial presence animation.                                                                                                                                                                              |
| `unmountOnExit`          | `boolean`                                  | No       | Whether to unmount on exit.                                                                                                                                                                                                   |

### Anchor Props

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

### Arrow Props

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Arrow CSS Variables

| Variable             | Description                                     |
| -------------------- | ----------------------------------------------- |
| `--arrow-size`       | The size of the arrow                           |
| `--arrow-size-half`  | Half the size of the arrow                      |
| `--arrow-background` | Use this variable to style the arrow background |
| `--arrow-offset`     | The offset position of the arrow                |

### ArrowTip Props

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

### CloseTrigger Props

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

### Content Props

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Content Data Attributes

| Attribute           | Value                        |
| ------------------- | ---------------------------- |
| `[data-scope]`      | popover                      |
| `[data-part]`       | content                      |
| `[data-state]`      | "open" \| "closed"           |
| `[data-nested]`     | popover                      |
| `[data-has-nested]` | popover                      |
| `[data-expanded]`   | Present when expanded        |
| `[data-placement]`  | The placement of the content |

#### Content CSS Variables

| Variable               | Description                                     |
| ---------------------- | ----------------------------------------------- |
| `--layer-index`        | The index of the dismissable in the layer stack |
| `--nested-layer-count` | The number of nested popovers                   |

### Description Props

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

### Indicator Props

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Indicator Data Attributes

| Attribute      | Value              |
| -------------- | ------------------ |
| `[data-scope]` | popover            |
| `[data-part]`  | indicator          |
| `[data-state]` | "open" \| "closed" |

### Positioner Props

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Positioner CSS Variables

| Variable             | Description                         |
| -------------------- | ----------------------------------- |
| `--reference-width`  | The width of the reference element  |
| `--reference-height` | The height of the root              |
| `--available-width`  | The available width in viewport     |
| `--available-height` | The available height in viewport    |
| `--x`                | The x position for transform        |
| `--y`                | The y position for transform        |
| `--z-index`          | The z-index value                   |
| `--transform-origin` | The transform origin for animations |

### RootProvider Props

| Prop                   | Type               | Required | Description                                                                         |
| ---------------------- | ------------------ | -------- | ----------------------------------------------------------------------------------- |
| `value`                | `UsePopoverReturn` | Yes      |                                                                                     |
| `immediate`            | `boolean`          | No       | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount`            | `boolean`          | No       | Whether to enable lazy mounting                                                     |
| `onExitComplete`       | `VoidFunction`     | No       | Function called when the animation ends in the closed state                         |
| `present`              | `boolean`          | No       | Whether the node is present (controlled by the user)                                |
| `skipAnimationOnMount` | `boolean`          | No       | Whether to allow the initial presence animation.                                    |
| `unmountOnExit`        | `boolean`          | No       | Whether to unmount on exit.                                                         |

### Title Props

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

### Trigger Props

| Prop      | Type      | Required | Description                                                                                         |
| --------- | --------- | -------- | --------------------------------------------------------------------------------------------------- |
| `asChild` | `boolean` | No       | Use the provided child element as the default rendered element, combining their props and behavior. |

#### Trigger Data Attributes

| Attribute          | Value                        |
| ------------------ | ---------------------------- |
| `[data-scope]`     | popover                      |
| `[data-part]`      | trigger                      |
| `[data-placement]` | The placement of the trigger |
| `[data-state]`     | "open" \| "closed"           |


---
## portal

---
title: 'Portal'
description: 'Portal displays content in outside of the DOM hierarchy.'
npm: '@cerberus-design/react'
source: 'components/portal'
---




```ts

```

## Usage

}>
```tsx title="nav.tsx" {23}
'use client'






function PortalPreview() {
  const [showPortal, setShowPortal] = useState<boolean>(false)

  function handleShowPortal() {
    setShowPortal(true)
  }

  function handleClosePortal() {
    setShowPortal(false)
  }

  return (
    <>
      <Button onClick={handleShowPortal}>Show Portal</Button>
      <Show when={showPortal}>
        <Portal>
          <div
            className={hstack({
              backgroundColor: 'info.surface.initial',
              color: 'info.text.initial',
              justify: 'space-between',
              left: 0,
              mxi: '4',
              p: '4',
              position: 'absolute',
              right: 0,
              rounded: 'md',
              shadow: 'md',
              top: '4',
              zIndex: 'toast',
            })}
          >
            <p>
              This is a portal element that is outside of the DOM hierarchy of
              the parent component.
            </p>

            <IconButton
              ariaLabel="Close Portal"
              onClick={handleClosePortal}
              tooltipPosition="bottom"
            >
              <Close />
            </IconButton>
          </div>
        </Portal>
      </Show>
    </>
  )
}
```


## API

```ts showLineNumbers=false
export interface PortalProps {
  container?: RefObject<HTMLElement>;
  disabled?: boolean;
}

define function Portal(props: PropsWithChildren<PortalProps>): ReactPortal | null
```

### Props

The `Portal` component accepts the following props:

| Name     | Default | Description                                                   |
| -------- | ------- | ------------------------------------------------------------- |
| container     | `document.body`   | The mounted element to place the children contents within. |
| disabled | `false` | Disables the portal from rendering. Perfect for when you need to disabled a child Portal that is rendered within another Portal. |


---
## presence

---
title: 'Presence'
description: Helps control the rendering and unmounting of your content based on a given state.
npm: '@cerberus/react'
arkUtility: 'presence'
---

## Examples

By default the child component starts out as hidden and remains hidden after the `present` state is toggled off. This is
useful for situations where the element needs to be hidden initially and continue to stay hidden after its presence is
no longer required.


```tsx
'use client'




export const Basic = () => {
  const [present, setPresent] = useState(false)
  return (
    <>
      <button type="button" onClick={() => setPresent(!present)}>
        Toggle
      </button>
      <Presence present={present}>Hidden and Hidden</Presence>
    </>
  )
}
```


### Lazy Mount

To delay the mounting of a child component until the `present` prop is set to true, use the `lazyMount` prop:


```tsx
'use client'




export const LazyMount = () => {
  const [present, setPresent] = useState(false)
  return (
    <>
      <button type="button" onClick={() => setPresent(!present)}>
        Toggle
      </button>
      <Presence present={present} lazyMount>
        Unmounted and Hidden
      </Presence>
    </>
  )
}

```

### Unmount on Exit

To remove the child component from the DOM when it's not present, use the `unmountOnExit` prop:


```tsx
'use client'




export const UnmountOnExit = () => {
  const [present, setPresent] = useState(false)
  return (
    <>
      <button type="button" onClick={() => setPresent(!present)}>
        Toggle
      </button>
      <Presence present={present} unmountOnExit>
        Hidden and Unmounted on Exit
      </Presence>
    </>
  )
}

```


### Combining Lazy Mount and Unmount on Exit

Both `lazyMount` and `unmountOnExit` can be combined for a component to be mounted only when it's present and to be
unmounted when it's no longer present:

```tsx
'use client'




export const LazyMountAndUnmountOnExit = () => {
  const [present, setPresent] = useState(false)
  return (
    <>
      <button type="button" onClick={() => setPresent(!present)}>
        Toggle
      </button>
      <Presence present={present} lazyMount unmountOnExit>
        Lazy Mount and Unmounted on Exit
      </Presence>
    </>
  )
}

```


## API Reference


| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


---
## progress

---
title: 'Progress Indicators'
description: 'Progress indicators are used to show the progress of a task.'
npm: '@cerberus-design/react'
source: 'components/progress'
recipe: 'slots/progressBar.ts'
ark: 'progress-circular'
---


import {
  NoteAdmonition
} from '@/app/components/Admonition'



```tsx

```

## Usage

### Progress Bar

The `ProgressBar` component is used to display a linear progress indicator. It can be used in both determinate and indeterminate states.

}>
```tsx



export function OverviewPreview() {
  return (
    <HStack
      gap="10"
      w="3/4"
    >
      <VStack gap="md" w="full">
        <ProgressBar
          id="rounded-example"
          label="rounded progress example"
          size="sm"
          now={75}
        />
        <Tag shape="pill">Rounded</Tag>
      </VStack>
      <VStack gap="md" w="full">
        <ProgressBar
          id="block-example"
          label="block progress example"
          size="sm"
          usage="block"
          now={75}
        />
        <Tag shape="pill">Block</Tag>
      </VStack>
    </HStack>
  )
}
```


## Circular Progress

The `CircularProgress` component is used to display a circular progress indicator. It will scale to the size of its container.

}>
```tsx
'use client'




function NotStartedText() {
  return (
    <Text textAlign="center" textStyle="heading-2xs" px="md">
      Not Started
    </Text>
  )
}

function CircularPreview() {
  return (
    <HStack>
      <CircularProgress
        id="0"
        defaultValue={0}
        label={<NotStartedText />}
        hideValueText
      />
      <CircularProgress id="25" defaultValue={25} />
      <CircularProgress id="50" defaultValue={50} />
      <CircularProgress id="75" defaultValue={75} />
      <CircularProgress id="complete" label="complete" defaultValue={100} />
    </HStack>
  )
}
```


### Sizes

The `CircularProgress` component supports different sizes via the `size` prop.

}>
```tsx
function SizesPreview() {
  return (
    <HStack w="1/2">
      <CircularProgress id="25" defaultValue={25} size="xs" />
      <CircularProgress id="50" defaultValue={50} size="sm" />
      <CircularProgress id="75" defaultValue={75} size="md" />
      <CircularProgress
        id="complete"
        label="complete"
        defaultValue={100}
        size="lg"
      />
    </HStack>
  )
}
```


### Hide Value Text

The `CircularProgress` component allows you to hide the value text via the `hideValueText` prop.

}>
```tsx /hideValueText/
function HideValueTextPreview() {
  return (
    <HStack justify="center" w="1/2">
      <CircularProgress
        defaultValue={0}
        label={<NotStartedText />}
        hideValueText
      />
    </HStack>
  )
}
```


### Custom Label

You can customize the label displayed below the value by passing a custom React node to the `label` prop.

} >
```tsx /label/
function CustomLabelPreview() {
  return (
    <HStack justify="center" w="1/2">
      <CircularProgress
        defaultValue={60}
        label={
          <Text color="yellow" textStyle="heading-sm">
            Loading
          </Text>
        }
      />
    </HStack>
  )
}
```


## Primitives

You can utilize the primitive components or style props to customize the progress components.

### Progress Bar

| Component | Description |
| --------- | ----------- |
| ProgressBarRoot    | The container for the ProgressBar parts |
| ProgressBarBar  | The percentage bar of the amount |

### Circular Progress

| Component | Description |
| --------- | ----------- |
| CircularProgressRoot    | The context provider for the CircularProgress parts |
| CircularProgressInfoGroup  | The container for the text parts |
| CircularProgressLabel  | The descriptive text below the value |
| CircularProgressValueText  | The value of the progress, displayed in the center circle |
| CircularProgressCircle  | The container of the progress |
| CircularProgressCircleTrack  | The track of the progress |
| CircularProgressCircleRange  | The range of the progress |

### CSS Variables

Both `ProgressBar` and `CircularProgress` components expose CSS variables for easy customization.

| Variable Name               | Description                               |
| --------------------------- | ----------------------------------------- |
| `--percent`                 | The percent value for the root.           |
| `--radius`                  | The border radius value.                  |
| `--circumference`           | The circumference value for the root.     |
| `--offset`                  | The offset position of the element        |

### Data Attributes

Both `ProgressBar` and `CircularProgress` components expose data attributes for styling based on state.

| Data Attribute              | Value.                                    |
| --------------------------- | ----------------------------------------- |
| `[data-scope]`              | progress                                  |
| `[data-part]`               | The primitive layer (e.g. 'root')         |
| `[data-max]`                | The value of `max`                        |
| `[data-value]`              | The value of the progress                 |
| `[data-state]`              | The state of the progress (e.g. 'loading') |
| `[data-orientation]`      | The orientation of the progress (e.g. 'horizontal', 'vertical')        |

## API

### ProgressBar

| Name     | Default | Description                                  |
| -------- | ------- | -------------------------------------------- |
| id |    | The id of the CircularProgress. |
| label |    | A description of what the progress bar is for. |
| size |  `md`  | The size of the progress bar. |
| usage |  `rounded`  | The style of the progress bar. |
| now |    | The current progress value. |
| indeterminate |  `false`  | If the progress bar is in an indeterminate state. |

### CircularProgress

| Name     | Default | Description                                  |
| -------- | ------- | -------------------------------------------- |
| hideValueText |  `false`  | Hides the value text in the center of the circle. |
| label    |    | A description of what the progress bar is for. |
| size     |  `md`  | The size of the circular progress. |
| usage    |  `filled`  | The fill style of the center circle used for the bg. |

The `CircularProgress` component also accepts all the props of the [`CircularProgressRoot` primitive props](https://ark-ui.com/react/docs/components/progress-circular#api-reference)


---
## prompt-modal

---
title: Prompt Modal
description: The Prompt Modal is used to prompt the user for input, such as a passkey or confirmation for destructive actions.
npm: '@cerberus-design/react'
source: 'context/prompt-modal.tsx'
recipe: 'slots/dialog.ts'
ark: 'dialog'
---


import {
  NoteAdmonition,
} from '@/app/components/Admonition'
import {
  NonDestructivePreview,
  DestructivePreview,
} from '../components/prompt-modal/static'

```ts

```

## Usage

### Non-destructive

}>
```tsx title="some-page.tsx" {9}


function SomeFeature() {
  const prompt = usePromptModal()
  const [userValue, setUserValue] = useState<string | null>(null)

  const handleClick = useCallback(async () => {
    const key = 'SUPER_SECRET'
    const userPrompt = await prompt.show({
      heading: 'Enter passkey',
      description:
        'In order to view the super secret stuff you need to enter your passkey.',
      key,
      actionText: 'Copy passkey',
      cancelText: NOPE,
    })
    if (userPrompt === key) setUserValue('Super secret stuff')
  }, [prompt])

  return (
    <Button onClick={handleClick}>View passkey</Button>
  )
}

function SomePage() {
  return(
    <PromptModal>
      <SomeFeature />
    </PromptModal>
  )
}
```


### Destructive

}>
```tsx title="some-page.tsx" {10}


function SomeFeature() {
  const prompt = usePromptModal()
  const [userValue, setUserValue] = useState<string | null>(null)

  const handleClick = useCallback(async () => {
    const key = 'DELETE'
    const userConsent = await prompt.show({
      kind: 'destructive',
      heading: 'Remove payment method?',
      description: 'This is a permanent action and cannot be undone.',
      key,
      actionText: 'Yes, delete',
      cancelText: NOPE,
    })
    if (userConsent === key) setUserValue('Payment method removed')
  }, [prompt])

  return (
    <Button palette="danger" onClick={handleClick}>Delete card</Button>
  )
}

function SomePage() {
  return(
    <PromptModal>
      <SomeFeature />
    </PromptModal>
  )
}
```


## Primitives

The PromptModal is an abstraction of the [Dialog primitives](./dialog) and does not provide any additional customization. To build your own PromptModal, use the `Dialog` components.

## API

```ts showLineNumbers=false
export interface PromptModalProviderValue {
  show: (options: PromptModalOptions) => Promise<string>
}

define function PromptModal(props: PropsWithChildren<DialogRootProps>): ReactNode
````

###  PromptModal

The `PromptModal` component is an abstraction of the Dialog and accepts the same 
props as the `Dialog` component.

### Show Method Options

The `show` method accepts the following options:

| Name     | Default | Description                            |
| -------- | ------- | -------------------------------------- |
| kind | `non-destructive` | The variant used to theme the modal.           |
| heading |  | The heading of the modal. |
| description |  | The description of the modal. |
| key |  | A string key to test the user input against. |
| actionText |  | The text for the action button. |
| cancelText |  | The text for the cancel button. |


---
## radio

---
title: Radio
description: The Radio component allows users to select one option from a set of choices.
npm: '@cerberus-design/react'
source: 'components/radio'
recipe: 'slots/radio.ts'
ark: 'radio-group'
---





```ts

```

## Usage

The Radio component is a controlled component that can be used to select one option from a set. Simply wrap the `Radio` components in a `RadioGroup` component to create a group of radio buttons.

}>
```tsx title="basic demo"


export function BasicDemo() {
  return (
    <RadioGroup defaultValue="cerberus">
      <Radio value="cerberus">Cerberus</Radio>
      <Radio value="hades">Hades</Radio>
      <Radio value="zeus">Zeus</Radio>
    </RadioGroup>
  )
}
```


## Orientation

The `RadioGroup` component supports two orientations: `horizontal`, and `vertical`. The default orientation is `horizontal`.

}>
```tsx title="Orientation demo" /orientation/


export function OrientationDemo() {
  return (
    <RadioGroup defaultValue="cerberus" orientation="vertical">
      <Radio value="cerberus">Cerberus</Radio>
      <Radio value="hades">Hades</Radio>
      <Radio value="zeus">Zeus</Radio>
    </RadioGroup>
  )
}
```


## Sizes

The Radio component supports two sizes: `sm`, and `md`. The default size is `sm`.

}>
```tsx title="size demo"


export function SizeDemo() {
  return (
    <RadioGroup defaultValue="cerberus">
      <Radio size="md" value="cerberus">Cerberus</Radio>
      <Radio size="md" value="hades">Hades</Radio>
      <Radio size="md" value="zeus">Zeus</Radio>
    </RadioGroup>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the radio.

| Component | Description |
| --------- | ----------- |
| RadioGroupRoot    | The context provider for the RadioGroup parts |
| RadioGroupLabel   | The label of the radio |
| RadioGroupIndicator   | The indicator of the radio state |
| RadioGroupItem   | The container of the label and control of the radio |
| RadioGroupItemText | The label for a single radio |
| RadioGroupItemControl | The visual input of a single radio |
| RadioGroupItemHiddenInput  | The native input for the radio |

}>
```tsx title="custom radio demo" {8-10}


function CustomDemo() {
  return (
    <RadioParts.Root>
      <RadioParts.Item>
        <RadioParts.ItemText
          css={{
            textStyle: 'body-lg',
          }}
        >
          Cerberus
        </RadioParts.ItemText>
        <RadioParts.ItemControl
          css={{
            bgColor: 'info.bg.initial',
            h: 8,
            w: 8,
            transform: 'skew(-10deg)',
            _checked: {
              bg: 'warning.bg.initial',
            },
          }}
        />
        <RadioParts.ItemHiddenInput />
      </RadioParts.Item>
    </RadioParts.Root>
  )
}
```



## API

### Props

#### RadioGroup

The `RadioGroup` component is an abstraction of the primitives and accepts the following props:

| Name     | Default | Description                                            |
| -------- | ------- | ------------------------------------------------------ |
| orientation |  `horizontal`   | This orientation of the group.              |


The `RadioGroup` component also accepts all the props of the [`RadioGroupRoot` primitive props](https://ark-ui.com/react/docs/components/radio-group#api-reference)

#### Radio

The `Radio` component is an abstraction of the primitives and accepts the following props:

| Name     | Default | Description                                            |
| -------- | ------- | ------------------------------------------------------ |
| size |  `sm`   | The size of the radio.                                     |

The `Radio` component also accepts all the props of the [`RadioGroupItem` primitive props](https://ark-ui.com/react/docs/components/radio-group#api-reference)

### Parts

The `RadioParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the RadioParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name     | Description                            |
| -------- | -------------------------------------- |
| Root     | The `RadioGroupRoot` component which is the Provider for the family. |
| Label     | The `RadioGroupLabel` component which displays the label and "required" notice. |
| Indicator  | The `RadioGroupIndicator` component which displays based on the `checked` state. |
| Item  | The `RadioGroupItem` component which is the container to a single radio item. |
| ItemText  | The `RadioGroupItemText` component which is the label of the radio. |
| ItemControl     | The `RadioGroupItemControl` component which is the visual field. |
| HiddenInput  | The `RadioGroupHiddenInput` component which displays the native input. |


---
## rating

---
title: Rating
description: The Rating component provides a way to select a value from a range of values, typically used for feedback on a scale.
npm: '@cerberus-design/react'
source: 'components/rating'
recipe: 'slots/ratingGroup.ts'
ark: 'rating-group'
---





```ts

```

## Usage

The `Rating` component is an abstracted `client` component that provides a way to select a value from a range of values. It is used to provide feedback on a scale. The default `count` is 5, and the default `value` is 0.

}>
```tsx title="basic demo"
'use client'




export function BasicDemo() {
  return <Rating defaultValue={3}>{() => <StarFilled size={24} />}</Rating>
}
```


## Readonly State

To render the `Rating` component in a read-only state, you can use the `readOnly` prop.

}>
```tsx title="readonly demo"
'use client'




function ReadOnlyHalfDemo() {
  return (
    <Rating defaultValue={4.5} allowHalf readOnly>
      {({ half, highlighted }) => {
        if (half) return <StarHalf size={24} />
        if (highlighted) return <StarFilled size={24} />
        return <Star size={24} />
      }}
    </Rating>
  )
}
```


## Orientation

The `Rating` component supports two layout orientations for label usage: `horizontal`, and `vertical`. The default orientation is `vertical`.

}>
```tsx title="Orientation demo" {10-11}
'use client'




function OrientationDemo() {
  return (
    <Box w="1/2">
      <Rating
        allowHalf
        defaultValue={4.5}
        label="Average Rating"
        orientation="horizontal"
        readOnly
      >
        {({ half }) => {
          if (half) return <StarHalf size={24} />
          return <StarFilled size={24} />
        }}
      </Rating>
    </Box>
  )
}
```


## Sizes

The Rating component supports two sizes: `sm`, and `md`. The default size is `sm`.

}>
```tsx title="size demo" {8}
'use client'




function SizeDemo() {
  return (
    <Rating defaultValue={3} label="This is a medium label" size="md">
      {() => <StarFilled size={24} />}
    </Rating>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the radio.

| Component | Description |
| --------- | ----------- |
| RatingRoot    | The context provider for the Rating parts |
| RatingLabel   | The label of the rating |
| RatingControl | The visual control of the rating  |
| RatingContext | The context provider for the rating |
| RatingItem   | The container of the rating item |
| RatingItemContext | The context provider for a rating item |
| RatingHiddenInput  | The native input for the rating |

}>
```tsx title="custom rating demo"



function CustomDemo() {
  return (
    <Box w="1/2">
      <RatingParts.Root
        defaultValue={3}
        orientation="horizontal"
        css={{
          transform: 'skewX(-10deg)',
        }}
      >
        <RatingParts.Label
          css={{
            textStyle: 'heading-xs',
            textTransform: 'uppercase',
          }}
        >
          This is a custom rating
        </RatingParts.Label>

        <RatingParts.Control>
          <RatingParts.Context>
            {(context: UseRatingGroupContext) =>
              context.items.map((item) => (
                <RatingParts.Item
                  key={item}
                  index={item}
                  css={{
                    _highlighted: {
                      colorPalette: 'danger',
                      scale: '1.2',
                    },
                  }}
                >
                  <RatingParts.ItemContext>
                    {() => <StarFilled size={24} />}
                  </RatingParts.ItemContext>
                </RatingParts.Item>
              ))
            }
          </RatingParts.Context>
          <RatingParts.HiddenInput />
        </RatingParts.Control>
      </RatingParts.Root>
    </Box>
  )
}
```



## API

### Props

#### Rating

The `Rating` component is an abstraction of the primitives and accepts the following props:

| Name     | Default | Description                                            |
| -------- | ------- | ------------------------------------------------------ |
| orientation |  `horizontal`   | This orientation of the group.              |
| palette |  `action`   | The color palette of the items .                    |
| size |  `sm`   | The size of the label.                                     |


The `Rating` component also accepts all the props of the [`RatingRoot` primitive props](https://ark-ui.com/react/docs/components/rating-group#api-reference)

### Parts

The `RatingParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the RatingParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name     | Description                            |
| -------- | -------------------------------------- |
| Root     | The `RatingRoot` component which is the Provider for the family. |
| Label    | The `RatingLabel` component which displays the label. |
| Control  | The `RatingControl` component which displays the visual rating. |
| Item  | The `RatingItem` component which is the container to a single item. |
| ItemContext     | The `RatingItemContext` component which is the context provider for a single item. |
| HiddenInput  | The `RatingHiddenInput` component which displays the native radio. |


---
## scrollable

---
title: Scrollable
description: A layout pattern to create scrollable containers.
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The `Scrollable` component provides an easy way to create scrollable containers
without having to worry about overflow styles.


```tsx



export function BasicDemo() {
  return (
    <Scrollable h="200px" w="3/4">
      <Text>
        It was the best compliment that he&apos;d ever received although the person who
        gave it likely never knew. It had been an off-hand observation on his ability to
        hold a conversation and actually add pertinent information to it on practically
        any topic. Although he hadn&apos;t consciously strived to be able to do so,
        he&apos;d started to voraciously read the news when he couldn&apos;t keep up on
        topics his friends discussed because their conversations went above his head.
        The fact that someone had noticed enough to compliment him that he could talk
        intelligently about many topics meant that he had succeeded in his quest to be
        better informed.
      </Text>
      <Text>
        The wolves stopped in their tracks, sizing up the mother and her cubs. It had
        been over a week since their last meal and they were getting desperate. The cubs
        would make a good meal, but there were high risks taking on the mother Grizzly.
        A decision had to be made and the wrong choice could signal the end of the pack.
      </Text>
    </Scrollable>
  )
}
```


## Direction

Use `vertical` or `horizontal` to control the overflow scrolling direction.


```tsx



export function DirectionDemo() {
  return (
    <Scrollable direction="horizontal" w="3/4">
      <Text textWrap="nowrap">
        It was the best compliment that he&apos;d ever received although the person who
        gave it likely never knew. It had been an off-hand observation on his ability to
        hold a conversation and actually add pertinent information to it on practically
        any topic. Although he hadn&apos;t consciously strived to be able to do so,
        he&apos;d started to voraciously read the news when he couldn&apos;t keep up on
        topics his friends discussed because their conversations went above his head.
        The fact that someone had noticed enough to compliment him that he could talk
        intelligently about many topics meant that he had succeeded in his quest to be
        better informed.
      </Text>
    </Scrollable>
  )
}
```


## Scrollbar visibility

You can control the visibility of the scrollbar using the `hideScrollbar` prop.


```tsx



export function VisibiltyDemo() {
  return (
    <Scrollable hideScrollbar h="200px" w="3/4">
      <Text>
        It was the best compliment that he&apos;d ever received although the person who
        gave it likely never knew. It had been an off-hand observation on his ability to
        hold a conversation and actually add pertinent information to it on practically
        any topic. Although he hadn&apos;t consciously strived to be able to do so,
        he&apos;d started to voraciously read the news when he couldn&apos;t keep up on
        topics his friends discussed because their conversations went above his head.
        The fact that someone had noticed enough to compliment him that he could talk
        intelligently about many topics meant that he had succeeded in his quest to be
        better informed.
      </Text>
      <Text>
        The wolves stopped in their tracks, sizing up the mother and her cubs. It had
        been over a week since their last meal and they were getting desperate. The cubs
        would make a good meal, but there were high risks taking on the mother Grizzly.
        A decision had to be made and the wrong choice could signal the end of the pack.
      </Text>
    </Scrollable>
  )
}
```


## Props

The `Scrollable` component supports all CSS properties as props, along with the following additional props:

| Prop            | Type                         | Description                                |
| --------------- | ---------------------------- | ------------------------------------------ |
| `direction`     | `'vertical' \| 'horizontal'` | Controls the overflow scrolling direction. |
| `hideScrollbar` | `boolean`                    | Hides the scrollbar.                       |


---
## select

---
title: Select
description: The Select component is a controlled component that can be used to select one option from a set. It can be used in a group with other selects to allow for multiple selections.
npm: '@cerberus-design/react'
source: 'components/select'
recipe: 'slots/select.ts'
ark: 'select'
---






```ts
import {
  Select,
  Option,
  OptionGroup,
  OptionGroupLabel,
  createSelectCollection
} from '@cerberus/react'
```

## Usage

The `Select` component is a controlled component that can be used to select one option from a set. It can be used in a group with other selects to allow for multiple selections.

}>
```tsx
import {
  For,
  Field,
  Select,
  Option,
  createSelectCollection
} from '@cerberus/react'


function SelectBasicPreview() {
  const collection = createSelectCollection([
    { label: 'Hades', value: 'hades' },
    { label: 'Persephone', value: 'persephone' },
    { label: 'Zeus', value: 'zeus', disabled: true },
    { label: 'Poseidon', value: 'poseidon' },
    { label: 'Hera', value: 'hera' },
  ])

  return (
    <Box w="1/2">
      <Field label="Select Relative">
        <Select collection={collection} placeholder="Choose option">
          <For each={collection.items}>
            {(item) => <Option key={item.value} item={item} />}
          </For>
        </Select>
      </Field>
    </Box>
  )
}
```


## Grouped Options

To group options, use the `OptionGroup` and `OptionGroupLabel` components.

}>
```tsx
import {
  For,
  Field,
  Select,
  Option,
  OptionGroup,
  OptionGroupLabel,
  createSelectCollection
} from '@cerberus/react'


function GroupedOptionsDemo() {
  const collection = createSelectCollection([
    { label: 'Hades', value: '1-hades' },
    { label: 'Persephone', value: '1-persephone' },
    { label: 'Zeus', value: '1-zeus', disabled: true },
    { label: 'Poseidon', value: '1-poseidon' },
    { label: 'Hera', value: '1-hera' },
  ])

  return (
    <Box w="1/2">
      <Field label="Select Relative">
        <Select collection={collection} placeholder="Choose option">
          <OptionGroup>
            <OptionGroupLabel>The fam</OptionGroupLabel>
            <For each={collection.items}>
              {(item) => <Option key={item.value} item={item} />}
            </For>
          </OptionGroup>
        </Select>
      </Field>
    </Box>
  )
}
```


## With Dialog

}>
```tsx title="Select with Dialog Demo" {16, 30-32}
'use client'

import {
  Dialog,
  DialogCloseIconTrigger,
  DialogDescription,
  DialogHeading,
  DialogProvider,
  DialogTrigger,
} from '@cerberus/react'



export function SelectWithDialogDemo() {
  return (
    <DialogProvider>
      <DialogTrigger>Open Select Dialog</DialogTrigger>
      <Dialog>
        <VStack alignItems="flex-start" gap="lg" w="full">
          <DialogCloseIconTrigger />
          <DialogHeading>Some heading</DialogHeading>
          <DialogDescription>
            This is a description for the dialog. You can use this space to
            provide more context or instructions for the user.
          </DialogDescription>

          <Box w="full">
            <SelectBasicPreview />
          </Box>
        </VStack>
      </Dialog>
    </DialogProvider>
  )
}

```


## Primitives

You can utilize the primitive components or the `css` prop to customize the select.

| Component | Description |
| --------- | ----------- |
| SelectRoot    | The context provider for the Select family |
| SelectLabel   | The label that appears above the select input |
| SelectControl | The wrapper to the select trigger that opens the dropdown |
| SelectTrigger | he trigger that opens the dropdown |
| SelectValueText | The text that appears in the trigger |
| SelectIndicator | The indicator that appears in the trigger |
| SelectClearTrigger | The trigger that clears the selected value |
| SelectPositioner | The wrapper that positions the dropdown |
| SelectContent | The content of the dropdown (i.e. the container itself) |
| SelectItemGroup | The group of options in the dropdown |
| SelectItemGroupLabel | The label for the group of options |
| SelectItem | The option in the dropdown |
| SelectItemText | The text label of the option |
| SelectItemIndicator | The indicator shown when the option is selected |
| SelectHiddenInput | The native select for the select group. |

}>
```tsx title="Custom Select Demo"
function SelectCustomPreview() {
  const collection = createSelectCollection([
    { label: 'Hades', value: '1-hades' },
    { label: 'Persephone', value: '1-persephone' },
    { label: 'Zeus', value: '1-zeus', disabled: true },
    { label: 'Poseidon', value: '1-poseidon' },
    { label: 'Hera', value: '1-hera' },
  ])

  return (
    <Box w="1/2">
      <SelectParts.Root collection={collection}>
        <SelectParts.Label
          css={{
            paddingBlock: 2,
            textStyle: 'body-sm',
            textTransform: 'uppercase',
          }}
        >
          Select a custom relative
        </SelectParts.Label>

        <SelectParts.Control>
          <SelectParts.Trigger
            className={cx(
              css({
                bgColor: 'black',
                color: 'danger.surface.initial',
                paddingInline: 4,
                paddingBlock: 3,
                _hover: {
                  bgColor: 'danger.surface.initial',
                  color: 'white',
                },
              }),
              hstack({
                justify: 'space-between',
                w: 'full',
              }),
            )}
          >
            <SelectParts.ValueText placeholder="Choose a custom option" />
            <SelectParts.Indicator
              css={{
                transitionProperty: 'transform',
                transitionDuration: 'fast',
                _open: {
                  transform: 'rotate(180deg)',
                },
              }}
            >
              <ChevronDownOutline />
            </SelectParts.Indicator>
          </SelectParts.Trigger>
          <SelectParts.ClearTrigger>Clear</SelectParts.ClearTrigger>
        </SelectParts.Control>

        <Portal>
          <SelectParts.Positioner css={{ w: 'var(--reference-width)' }}>
            <SelectParts.Content
              css={{
                bgColor: 'danger.surface.initial',
                p: 4,
              }}
            >
              <SelectParts.ItemGroup>
                <SelectParts.ItemGroupLabel
                  css={css({
                    fontWeight: 'bold',
                    textStyle: 'label-sm',
                    textTransform: 'uppercase',
                  })}
                >
                  The fam
                </SelectParts.ItemGroupLabel>

                <For each={collection.items}>
                  {(item, idx) => (
                    <SelectParts.Item key={item.value} item={item}>
                      <SelectParts.ItemText
                        css={{
                          color: 'white',
                          display: 'inline-block',
                        }}
                        style={{
                          paddingInlineStart: `calc(16px * ${idx})`,
                        }}
                      >
                        {item.label}
                      </SelectParts.ItemText>
                      <SelectParts.ItemIndicator>✓</SelectParts.ItemIndicator>
                    </SelectParts.Item>
                  )}
                </For>
              </SelectParts.ItemGroup>
            </SelectParts.Content>
          </SelectParts.Positioner>
        </Portal>
      </SelectParts.Root>
    </Box>
  )
}
```



## API

### Select

The `Select` component is an abstraction of our primitives and accepts the following props:

| Name     | Default | Description                                            |
| -------- | ------- | ------------------------------------------------------ |
| placeholder |         | The placeholder to show in the select trigger. |
| size        | 'md'    | The size of the select. |
| collection  |         | The collection of options to show in the dropdown. |

The `Select` component also accepts all the props of the [`SelectRoot` primitive props](https://ark-ui.com/react/docs/components/select#api-reference)

### Option

The `Option` component is an abstraction of our primitives and accepts the following props:

| Name     | Default | Description                                            |
| -------- | ------- | ------------------------------------------------------ |
| item     |       | The item to show in the dropdown. `SelectCollectionItem` |

The `Option` component also accepts all the props of the [`SelectItem` primitive props](https://ark-ui.com/react/docs/components/select#api-reference)

### OptionGroup

The `OptionGroup` component is an abstraction of our primitives and accepts the same props as the `SelectItemGroup` primitive.

### OptionGroupLabel

The `OptionGroupLabel` component is an abstraction of our primitives and accepts the same props as the `SelectItemGroupLabel` primitive.

### createSelectCollection

The `createSelectCollection` function is a utility function that creates a collection of options for the `Select` component.

```ts
export function createSelectCollection(
  collection: SelectCollectionItem[],
): ListCollection<SelectCollectionItem> {
  return createListCollection({
    items: collection,
  })
}
```

### Parts

The `SelectParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the SelectParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name     | Description                            |
| -------- | -------------------------------------- |
| Root     | The `SelectRoot` component which is the Provider for the family. |
| Label     | The `SelectLabel` component which displays the label and "required" notice. |
| Control     | The `SelectControl` component which is the visual field. |
| Trigger     | The `SelectTrigger` component which is the trigger for the dropdown. |
| ClearTrigger     | The `SelectClearTrigger` component which is the trigger to clear the selected value. |
| ValueText  | The `SelectValueText` component which displays the selected value. |
| Indicator  | The `SelectIndicator` component which displays the trigger indicator. |
| Positioner | The `SelectPositioner` component which is controls the positioning for the dropdown. |
| Content  | The `SelectContent` component which is the dropdown itself. |
| ItemGroup | The `SelectItemGroup` component which is the group of options in the dropdown. |
| ItemGroupLabel | The `SelectItemGroupLabel` component which is the label for the group of options. |
| Item     | The `SelectItem` component which is the option in the dropdown. |
| ItemText | The `SelectItemText` component which is the text label of the option. |
| ItemIndicator | The `SelectItemIndicator` component which displays based on the `checked` state. |
| HiddenInput  | The `SelectHiddenInput` component which displays the native input. |


---
## show

---
title: 'Show'
description: 'Show displays content in the UI based on a condition. Inspired by SolidJS.'
npm: '@cerberus-design/react'
source: 'components/show'
---

import {
  NoteAdmonition,
  WhenToUseAdmonition,
  WhenNotToUseAdmonition,
} from '@/app/components/Admonition'



```ts

```

> **Note:** If you need to toggle an action between states based on user interaction, use the Toggle.

## Usage

The Show component takes a `when` prop that determines whether the children or the `fallback` content should be rendered. If `when` is true, the children are rendered. If `when` is false, the `fallback` content is rendered.

### Eager Loading

When passing elements as children, they are rendered eagerly into the Virtual DOM.

}>
```tsx title="Eager Demo"
'use client'





export default function ShowPreview() {
  const [authenticated, setAuthenticated] = useState<boolean>(false)

  function handleChange(state: boolean) {
    setAuthenticated(state)
  }

  return (
    <VStack w="1/2">
      <ToggleParts.Root
        onPressedChange={handleChange}
        pressed={authenticated}
        asChild
      >
        <Button type="button">
          <ToggleParts.Indicator fallback={<>Sign in</>}>
            Sign out
          </ToggleParts.Indicator>
        </Button>
      </ToggleParts.Root>

      <Show
        when={authenticated}
        fallback={<Text>You are not allowed to enter!</Text>}
      >
        <Text>You are authenticated and can enter the gates of Hades!</Text>
      </Show>
    </VStack>
  )
}
```


### Lazy Loading

To defer rendering until the condition is true, you can pass a function as children. This function will only be called when the `when` condition is true.

> **Note:** Open the console to see when the lazy component is executed.

}>
```tsx title="Lazy Demo"
'use client'

function LazyPreview() {
  const [loaded, setLoaded] = useState<boolean>(false)

  function handleLoad() {
    setLoaded(true)
  }

  return (
    <VStack w="1/2">
      <Button type="button" onClick={handleLoad}>
        Load Content
      </Button>

      <Show when={loaded}>{() => <LazyComponent />}</Show>
    </VStack>
  )
}

function LazyComponent() {
  console.log('Lazy component executed')
  return <Text>This is a lazy loaded component!</Text>
}
```



## API

```ts showLineNumbers=false
export interface ShowProps {
  children: ReactNode | (() => ReactNode)
  when: boolean | null | undefined
  fallback?: ReactNode
}

define function Show(props: ShowProps): ReactNode | null
```

### Props

The `Show` component accepts the following props:

| Name     | Default | Description                                                   |
| -------- | ------- | ------------------------------------------------------------- |
| when     | false   | The condition to evalue for showing the children or fallback. |
| fallback | null    | The content to render when the condition is false.            |


## Understanding React Rendering: Eager vs. Lazy Execution

This section explains a fundamental concept in React development that affects when your components run their code, especially when using conditional rendering wrappers like `<Show>`. Understanding this difference is key to writing high-performance code and correctly controlling side effects, like data fetching.

### The Core Misunderstanding: Execution vs. Rendering

When a component updates, React goes through two main steps:

1. Execution: The JavaScript function of your component runs.
2. Rendering/V-DOM Update: The component's return value.

#### 1. Eager Execution
The JavaScript function of your component runs. (This is where your useState, useEffect, and data fetching logic execute). This pattern is what most developers instinctively use, but it causes the component's internal logic to run even if it's never shown on the screen.

```typescript
<Show when={isLoggedIn}>
  <DashboardThatFetchesData />
</Show>
```

##### What Happens Under the Hood (Compilation)

The reason this is called **Eager Execution** is because the JavaScript compiler (like Babel, which processes JSX) must resolve **all props** for the `<Show>` component before it can call the `Show` function.

1.**Parent Renders:** The parent component of `<Show>` runs.

2.**Eager Prop Evaluation:** The compiler sees `<DashboardThatFetchesData />` and immediately executes the `DashboardThatFetchesData` component function to figure out what to pass as the children prop.

3.**Side Effects Run:** Any logic or side effects within `DashboardThatFetchesData` (like a network request in `useEffect`) **will run now**.

4.**Show Renders:** The `<Show>` component function runs. It receives an **already-executed** React Element object as props.children. Since `isLoggedIn` is false, it returns null or the fallback, and the Dashboard is **not rendered** in the DOM.

<NoteAdmonition description="The key point: By the time the <Show> component decides not to render the children, it's too late—the child component's code has already run." />

#### 2. The Lazy Execution

To gain control over the Execution step, we must pass a **function** instead of an element object. This is known as the **Render Prop** pattern.

```typescript
<Show when={isLoggedIn}>
  {() => <DashboardThatFetchesData />}
</Show>
```

##### What Happens Under the Hood (Compilation)

1.**Parent Renders:** The parent component of `<Show>` runs.

2.**Lazy Prop Evaluation:** The compiler sees the prop value is a **plain JavaScript function** (`() => <DashboardThatFetchesData />`). It does **not** execute the function; it simply passes the function object as the `children` prop to `<Show>`.

3.**Show Renders:** The `<Show>` function runs.
  - If `isLoggedIn` is `false`: It returns `null` or the fallback. The `children` function is **never called, never executed**. Execution is successfully skipped.
  - If `isLoggedIn` is `true`: It calls the function: `props.children()`. This is the first moment the `DashboardThatFetchesData` function executes, and its side effects begin.


---
## split-button

---
title: Split Button
description: A button component that combines a primary action with a dropdown menu for additional actions.
npm: '@cerberus-design/react'
source: 'components/split-button'
---





```ts

```

## Usage

The SplitButton component combines a primary action button with a dropdown menu for additional related actions.

It's ideal for situations where you have a primary action that users perform most often, but also want to provide quick access to related secondary actions.

}>

```tsx



function StaticPreview() {
  return (
    <SplitButton>
      <MenuItem value="save">
        <Save size={16} />
        Save
      </MenuItem>
      <MenuItem value="save_as">
        <Save size={16} />
        Save As...
      </MenuItem>
      <MenuItem value="export">
        <Download size={16} />
        Export
      </MenuItem>
    </SplitButton>
  )
}
```



## Main Action

The SplitButton accepts all standard `Button` props for the primary action button, allowing you to customize its behavior.

}>
```tsx



function BasicDemo() {
  return (
    <SplitButton actionText="Main Action" pending>
      <MenuItem value="save">
        <Save size={16} />
        Save
      </MenuItem>
      <MenuItem value="save_as">
        <Save size={16} />
        Save As...
      </MenuItem>
      <MenuItem value="export">
        <Download size={16} />
        Export
      </MenuItem>
    </SplitButton>
  )
}
```


## Primitives

The SplitButton component is built using the following primitive components:

| Component    | Description                                           |
| ------------ | ----------------------------------------------------- |
| ButtonGroup  | Groups the primary button and dropdown trigger together |
| Button       | The primary action button                             |
| Menu         | The dropdown menu container. **Renders within parent context.**                           |
| MenuTrigger  | The dropdown trigger (IconButton)                    |
| MenuContent  | The dropdown menu content container                   |
| MenuItem     | Individual menu items within the dropdown            |

## API

### SplitButton

The `SplitButton` component accepts the following props:

| Name      | Default | Description                                      |
| --------- | ------- | ------------------------------------------------ |
| children  |         | MenuItem components to display in the dropdown  |
| actionText |         | The text for the primary action button          |

The SplitButton component internally uses:
- [ButtonGroup](https://cerberus.digitalu.design/docs/components/button) for layout
- [Button](https://cerberus.digitalu.design/docs/components/button) for the primary action
- [Menu](https://cerberus.digitalu.design/docs/components/menu) for the dropdown functionality
- [IconButton](https://cerberus.digitalu.design/docs/components/icon-button) for the dropdown trigger

### MenuItem

Use MenuItem components as children of SplitButton to define the available actions in the dropdown menu. See the [Menu documentation](https://cerberus.digitalu.design/docs/components/menu) for more details on MenuItem props.

> **Note:** The SplitButton component uses an attached ButtonGroup layout to ensure the primary button and dropdown trigger appear as a single unified control.


---
## split-props

---
title: 'splitProps'
description: 'A utility for splitting props into groups. Inspired by SolidJS.'
npm: '@cerberus-design/react'
source: 'utils/index.ts#L27-L49'
---

## Usage

```tsx title="text-field.tsx" {4-9}


function TextField(props: TextFieldProps) {
  const [rootProps, { size }, textFieldProps] = splitProps(
    props,
    ['required', 'readOnly', 'disabled', 'invalid', 'ids'],
    ['size'],
    ['helperText', 'errorText', 'label'],
  )

  return (
    <FieldParts.Root {...rootProps} size={size}>
      <FieldParts.Label>
        {textFieldProps.label}
        <Show when={rootProps.required}>
          <span data-part="required-text">(required)</span>
        </Show>
      </FieldParts.Label>

      <FieldParts.Input {...props.inputProps} size={size} />
      <FieldParts.HelperText>{textFieldProps.helperText}</FieldParts.HelperText>
      <FieldParts.ErrorText>{textFieldProps.errorText}</FieldParts.ErrorText>
    </FieldParts.Root>
  )
}
```

## API

```typescript
function splitProps<T, U extends string>(
  props: T,
  ...keys: [U[]] | [U[], U[]] | [U[], U[], U[]]
): [
  T,
  Partial<Pick<T, Extract<keyof T, U>>>,
  Partial<Pick<T, Exclude<keyof T, U>>>,
]
```

### Arguments

The `splitProps` utility accepts the following arguments:

| Name         | Default    | Description                                      |
| ------------ | ---------- | ------------------------------------------------ |
| props        |            | The Object to compare against.                   |
| keys         |            | A list of keys to split into a group.            |

### Returns

The `splitProps` utility returns an Array of the provided keys converted into an Object groups. What is left over is returned as the final Object in the array.


---
## stack

---
title: Stack
description: Used to layout its children in a vertical or horizontal stack.
panda: https://panda-css.com/docs/concepts/patterns#stack
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

By default, Stack applies `flex-direction: column` and `gap: 8px` to its
children.


```tsx



export function BasicDemo() {
  return (
    <Stack w="3/4">
      <DecorativeBox h="20" />
      <DecorativeBox h="20" />
      <DecorativeBox h="20" />
    </Stack>
  )
}
```


### Horizontal

Use the `direction` prop to change the direction of the stack.


```tsx



export function HorizontalDemo() {
  return (
    <Stack direction="horizontal" gap="md" w="3/4">
      <DecorativeBox h="10" />
      <DecorativeBox h="10" />
      <DecorativeBox h="10" />
    </Stack>
  )
}
```


### HStack

Alternatively, you can use the `HStack` to create a horizontal stack and align
its children horizontally.


```tsx



export function HStackDemo() {
  return (
    <HStack gap="md" w="3/4">
      <DecorativeBox h="10" />
      <DecorativeBox h="5" />
      <DecorativeBox h="20" />
    </HStack>
  )
}
```


### VStack

Use the `VStack` to create a vertical stack and align its children vertically.


```tsx



export function VStackDemo() {
  return (
    <VStack gap="md" w="3/4">
      <DecorativeBox h="20" w="50%" />
      <DecorativeBox h="20" w="25%" />
      <DecorativeBox h="20" w="full" />
    </VStack>
  )
}
```


## Responsive Direction


```tsx



export function ResponsiveStackDemo() {
  return (
    <Stack direction={{ base: 'column', md: 'row' }} gap="md" h="100px" w="3/4">
      <DecorativeBox boxSize="20" />
      <DecorativeBox boxSize="20" />
      <DecorativeBox boxSize="20" />
    </Stack>
  )
}
```


## Props

| Prop        | Type                                   | Description                           |
| ----------- | -------------------------------------- | ------------------------------------- |
| `direction` | `'row' \| 'column' \| ResponsiveValue` | The direction of the stack.           |
| `gap`       | `CerberusSpacing`                      | The gap between the stack items.      |
| `align`     | `CSSProperties['align-items']`         | The alignment of the stack items.     |
| `justify`   | `CSSProperties['justify-content']`     | The justification of the stack items. |


---
## switch

---
title: Switch
description: The Switch component is a toggle input that allows users to switch between two states.
npm: '@cerberus-design/react'
source: 'components/switch'
recipe: 'slots/switch.ts'
ark: 'switch'
---





```ts

```

## Usage

}>
```tsx title="valid-radio.tsx"



function BasicDemo() {
  return (
    <Box w="1/2">
      <Switch>Receive in app notifications</Switch>
    </Box>
  )
}
```


## With Field

To use the Switch within a form, wrap it with the [`Field`](./field) component.

}>
```tsx title="valid-radio.tsx"



function WithFieldDemo() {
  return (
    <Box w="1/2">
      <Field label="This is the field label" required>
        <Switch>Receive in app notifications</Switch>
      </Field>
    </Box>
  )
}
```


## Sizes

}>
```tsx title="valid-radio.tsx"



function SizesDemo() {
  return (
    <Box w="1/2">
      <VStack alignItems="flex-start" gap="lg">
        <Switch size="sm">Small size (default)</Switch>
        <Switch size="lg">Large size</Switch>
      </VStack>
    </Box>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the checkbox.

| Component | Description |
| --------- | ----------- |
| SwitchRoot    | The context provider for the switch parts |
| SwitchLabel   | The label of the switch |
| SwitchControl   | The visual input of the switch |
| SwitchThumb   | The thumb of the switch state |
| SwitchHiddenInput  | The native input for the switch |

}>
```tsx title="custom checkbox"



function CustomDemo() {
  return (
    <Box w="1/2">
      <SwitchParts.Root>
        <SwitchParts.Label
          css={{
            textTransform: 'uppercase',
          }}
        >
          Receive in app notifications
        </SwitchParts.Label>
        <SwitchParts.Control
          css={{
            rounded: 'sm',
            transform: 'skewX(-10deg)',
            _checked: {
              bgColor: 'danger.surface.initial',
            },
          }}
        >
          <SwitchParts.Thumb
            css={{
              rounded: 'sm',
            }}
          />
        </SwitchParts.Control>

        <SwitchParts.HiddenInput />
      </SwitchParts.Root>
    </Box>
  )
}
```


## API

### Props

The `Switch` component is an abstraction of the primitives and accepts the following props:

| Name     | Default | Description                                            |
| -------- | ------- | ------------------------------------------------------ |
| size     |  `sm`   | This size of the Switch.                             |


The `Switch` component also accepts all the props of the [`SwitchRoot` primitive props](https://ark-ui.com/react/docs/components/switch#api-reference)

### Parts

The `SwitchParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the SwitchParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name     | Description                            |
| -------- | -------------------------------------- |
| Root     | The `SwitchRoot` component which is the Provider for the family. |
| Label     | The `SwitchLabel` component which displays the label. |
| Control     | The `SwitchControl` component which is the visual field. |
| Thumb  | The `SwitchThumb` component which displays the thumb of the switch. |
| HiddenInput  | The `SwitchHiddenInput` component which displays the native input. |


---
## table

---
title: Table
description: The Table component is a controlled component that can be used to display tabular data.
npm: '@cerberus-design/react'
source: 'components/table'
recipe: 'slots/table.ts'
---


import {
  NoteAdmonition
} from '@/app/components/Admonition'
import {
  BasicTablePreview,
  SizesPreview,
  DecorationPreview,
  ItsGettingSticky,
  ClickablePreview,
  CustomizedPreview
} from '../components/table/static'

```tsx

```

## Usage

The Table component is a controlled component that can be used to display tabular data. It can be used in a group with other tables to allow for multiple selections.

}>
```tsx title="Basic demo"



function BasicTablePreview() {
  const items = [
    { id: 1, name: 'Laptop', category: 'Electronics', price: 999.99 },
    { id: 2, name: 'Coffee Maker', category: 'Home Appliances', price: 49.99 },
    { id: 3, name: 'Desk Chair', category: 'Furniture', price: 150.0 },
    { id: 4, name: 'Smartphone', category: 'Electronics', price: 799.99 },
    { id: 5, name: 'Headphones', category: 'Accessories', price: 199.99 },
  ]

  return (
    <Box w="1/2">
      <Table.Root caption="Basic table example">
        <Table.Header>
          <Table.Row>
            <Table.HeaderCol>Product</Table.HeaderCol>
            <Table.HeaderCol>Category</Table.HeaderCol>
            <Table.HeaderCol>Price</Table.HeaderCol>
          </Table.Row>
        </Table.Header>
        <Table.Body>
          <For each={items}>
            {(item) => (
              <Table.Row key={item.id}>
                <Table.Cell>{item.name}</Table.Cell>
                <Table.Cell>{item.category}</Table.Cell>
                <Table.Cell>{item.price}</Table.Cell>
              </Table.Row>
            )}
          </For>
        </Table.Body>
      </Table.Root>
    </Box>
  )
}
```


## Sizes

The `Table.Root` component supports different sizes for its cells. You can set the size of the table using the `size` prop. The available sizes are `sm`, `md`, and `lg`. The default size is `md`.

}>
```tsx title="Sizes demo"



function SizesPreview() {
  return (
    <HStack w="1/2">
      <Table.Root caption="Table with different cell sizes" size="sm">
        <Table.Header>
          <Table.Row>
            <Table.HeaderCol>Small</Table.HeaderCol>
          </Table.Row>
        </Table.Header>
        <Table.Body>
          <Table.Row>
            <Table.Cell>Small</Table.Cell>
          </Table.Row>
        </Table.Body>
      </Table.Root>

      <Table.Root caption="Table with different cell sizes" size="md">
        <Table.Header>
          <Table.Row>
            <Table.HeaderCol>Medium</Table.HeaderCol>
          </Table.Row>
        </Table.Header>
        <Table.Body>
          <Table.Row>
            <Table.Cell>Medium</Table.Cell>
          </Table.Row>
        </Table.Body>
      </Table.Root>

      <Table.Root caption="Table with different cell sizes" size="lg">
        <Table.Header>
          <Table.Row>
            <Table.HeaderCol>Large</Table.HeaderCol>
          </Table.Row>
        </Table.Header>
        <Table.Body>
          <Table.Row>
            <Table.Cell>Large</Table.Cell>
          </Table.Row>
        </Table.Body>
      </Table.Root>
    </HStack>
  )
}
```


## Decoration

The `Table.Root` component supports different decorations for its rows. You can set the decoration of the table using the `decoration` prop. The available decorations are `default` and `zebra`.

}>
```tsx title="Decoration demo"



function DecorationPreview() {
  return (
    <HStack w="1/2">
      <Table.Root caption="Table with default decorations">
        <Table.Header>
          <Table.Row>
            <Table.HeaderCol>Default</Table.HeaderCol>
          </Table.Row>
        </Table.Header>
        <Table.Body>
          <Table.Row>
            <Table.Cell>one</Table.Cell>
          </Table.Row>
          <Table.Row>
            <Table.Cell>two</Table.Cell>
          </Table.Row>
          <Table.Row>
            <Table.Cell>three</Table.Cell>
          </Table.Row>
        </Table.Body>
      </Table.Root>

      <Table.Root caption="Table with zebra decorations" decoration="zebra">
        <Table.Header>
          <Table.Row>
            <Table.HeaderCol>Zebra</Table.HeaderCol>
          </Table.Row>
        </Table.Header>
        <Table.Body>
          <Table.Row>
            <Table.Cell>one</Table.Cell>
          </Table.Row>
          <Table.Row>
            <Table.Cell>two</Table.Cell>
          </Table.Row>
          <Table.Row>
            <Table.Cell>three</Table.Cell>
          </Table.Row>
        </Table.Body>
      </Table.Root>
    </HStack>
  )
}
```


## Sticky

The `Table.Root` component supports a `sticky` prop, which makes the table header sticky. This is useful for long tables where you want to keep the header visible while scrolling.

> **Note:** The sticky prop removes the border from the table so you can provide it on the scrollable container for a better design experience.

}>
```tsx title="Sticky demo" {14}




function ItsGettingSticky() {
  return (
    <Scrollable
      border="1px solid"
      borderColor="page.border.200"
      h="10rem"
      rounded="md"
      w="1/2"
    >
      <Table.Root caption="Better find a mop, it's getting sticky..." sticky>
        <Table.Header>
          <Table.Row>
            <Table.HeaderCol>Product</Table.HeaderCol>
            <Table.HeaderCol>Category</Table.HeaderCol>
            <Table.HeaderCol>Price</Table.HeaderCol>
          </Table.Row>
        </Table.Header>
        <Table.Body>
          <For each={items}>
            {(item) => (
              <Table.Row key={item.id}>
                <Table.Cell>{item.name}</Table.Cell>
                <Table.Cell>{item.category}</Table.Cell>
                <Table.Cell>{item.price}</Table.Cell>
              </Table.Row>
            )}
          </For>
        </Table.Body>
      </Table.Root>
    </Scrollable>
  )
}
```


## Clickable

The `Table.HeaderCol` component supports a `Table.Trigger`, which renders a button element. This allows you to create clickable headers for sorting or other actions.

}>
```tsx title="Clickable demo" {35-40}
function ClickablePreview() {
  const [order, setOrder] = useState<'asc' | 'desc'>('asc')
  const data = useMemo(
    () => [
      {
        id: '1',
        name: 'John Doe',
        age: 30,
      },
      {
        id: '2',
        name: 'Jane Doe',
        age: 25,
      },
    ],
    [],
  )
  const sortedData = useMemo(() => {
    return order === 'asc'
      ? data.sort((a, b) => a.age - b.age)
      : data.sort((a, b) => b.age - a.age)
  }, [data, order])

  const handleClick = useCallback(() => {
    setOrder((prev) => (prev === 'asc' ? 'desc' : 'asc'))
  }, [])

  return (
    <Box w="1/2">
      <Table.Root caption="Clickable table">
        <Table.Header>
          <Table.Row>
            <Table.HeaderCol>Name</Table.HeaderCol>
            <Table.HeaderCol>
              <Table.Trigger onClick={handleClick}>
                Age
                <Show when={order === 'asc'} fallback={<SortDescending />}>
                  <SortAscending />
                </Show>
              </Table.Trigger>
            </Table.HeaderCol>
          </Table.Row>
        </Table.Header>
        <Table.Body>
          {sortedData.map((person) => (
            <Table.Row key={person.id}>
              <Table.Cell>{person.name}</Table.Cell>
              <Table.Cell>{person.age}</Table.Cell>
            </Table.Row>
          ))}
        </Table.Body>
      </Table.Root>
    </Box>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the table.

| Component | Description |
| --------- | ----------- |
| TableRoot     | The table container component. |
| TableEl  | The table component. |
| Caption | The caption component. |
| Thead | The table header component. |
| Th | The table header cell component. |
| Tbody | The table body component. |
| Tr | The table row component. |
| Td | The table cell component. |
| Tfoot | The table footer component. |
| TableTrigger | The table trigger component. |


}>
```tsx title="Custom example"


function CustomizedPreview() {
  const cols = [
    { id: '1', name: 'Cerberus Family' },
    { id: '2', name: 'Alias' },
  ]
  const data = [
    { id: '1', name: 'Cerberus', alias: 'The Three-Headed Dog' },
    { id: '2', name: 'Hades', alias: 'God of the Underworld' },
    { id: '3', name: 'Persephone', alias: 'Queen of the Underworld' },
    { id: '4', name: 'Charon', alias: 'The Ferryman' },
    { id: '5', name: 'Cerberus', alias: 'The Guardian of the Underworld' },
    { id: '6', name: 'Thanatos', alias: 'God of Death' },
  ]

  return (
    <Table.Root
      caption="Customized table"
      css={{
        border: '3px solid',
        borderColor: 'danger.border.initial',
        transform: 'skewX(-10deg)',
      }}
    >
      <Table.Header>
        <Table.Row>
          <For each={cols}>
            {(col) => (
              <Table.HeaderCol
                key={col.id}
                css={{
                  bgColor: 'black',
                  color: 'white',
                  width: '20rem',
                }}
              >
                {col.name}
              </Table.HeaderCol>
            )}
          </For>
        </Table.Row>
      </Table.Header>
      <Table.Body>
        <For each={data}>
          {(item) => (
            <Table.Row key={item.id}>
              <Table.Cell
                css={{
                  bgColor: 'gray.200',
                  color: 'black',
                  fontWeight: 'bold',
                }}
              >
                {item.name}
              </Table.Cell>
              <Table.Cell
                css={{
                  bgColor: 'gray.100',
                  color: 'black',
                }}
              >
                {item.alias}
              </Table.Cell>
            </Table.Row>
          )}
        </For>
      </Table.Body>
    </Table.Root>
  )
}
```


## API

### Props

The `Table` component is an abstraction of the primitives and accepts the following props:

| Name     | Default | Description                                            |
| -------- | ------- | ------------------------------------------------------ |
| caption  |  | The accessible caption of the Table.               |
| size     |  `md`   | This cell size of the Table.                           |
| decoration | `default` | The decoration of the Table.                       |
| sticky | `false` | If true, the table header will be sticky.                |

#### Table component parts

The `Table` API is an Object containing the full family of abstracted components.

> **Note:** Although the Table API is similar to the TableParts, it returns abstractions of the primitives. The TableParts return the primitives only.

| Name     | Description                            |
| -------- | -------------------------------------- |
| Root     | An abstraction of the `TableRoot`, `TableEl`, and `Caption`. |
| Header | The table header component. |
| HeaderCol | The table header cell component. |
| Body | The table body component. |
| Row | The table row component. |
| Cell | The table cell component. |
| Footer | The table footer component. |
| Trigger | The optional table header col trigger component. |

### Parts

The `TableParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the TableParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name     | Description                            |
| -------- | -------------------------------------- |
| Root     | The `TableRoot` component which is the container of the table. |
| Table  | The `TableEl` component which is the table element. |
| Caption | The `Caption` component which is the caption of the table. |
| Header | The `Thead` component which is the table header component. |
| HeaderCol | The `Th` component which is the table header cell component. |
| Body | The `Tbody` component which is the table body component. |
| Row | The `Tr` component which is the table row component. |
| Cell | The `Td` component which is the table cell component. |
| Footer | The `Tfoot` component which is the table footer component. |
| Trigger | The `TableTrigger` component which is the optional table header col trigger component. |


---
## tabs

---
title: Tabs
description: The Tabs component is used to create a tabbed interface.
npm: '@cerberus-design/react'
source: 'components/tabs'
recipe: 'slots/tabs.ts'
ark: 'tabs'
---



import {
  BasicTabsPreview,
  SecondaryTabsPreview,
  CustomTabsPreview,
  VerticalTabsPreview,
} from '../components/tabs/static'

```ts

```

## Usage

The `Tabs` component is used to create a tabbed interface.

}>
```tsx title="Basic demo"



export function BasicTabsPreview() {
  return (
    <Box w="1/2">
      <Tabs.Root defaultValue="overview">
        <Tabs.List>
          <Tabs.Tab value="overview">Overview</Tabs.Tab>
          <Tabs.Tab value="features">Features</Tabs.Tab>
          <Tabs.Tab value="pricing">Pricing</Tabs.Tab>
        </Tabs.List>
        <Tabs.Panel value="overview">Overview content</Tabs.Panel>
        <Tabs.Panel value="features">Features content</Tabs.Panel>
        <Tabs.Panel value="pricing">Pricing content</Tabs.Panel>
      </Tabs.Root>
    </Box>
  )
}
```


## Palette

The `palette` prop can be used to change the color of the Tabs.

}>
```tsx title="tabs.tsx" {4}
function SecondaryTabsPreview() {
  return (
    <Box w="1/2">
      <Tabs.Root defaultValue="overview-1" palette="secondaryAction">
        <Tabs.List>
          <Tabs.Tab value="overview-1">Overview</Tabs.Tab>
          <Tabs.Tab value="features-1">Features</Tabs.Tab>
          <Tabs.Tab value="pricing-1">Pricing</Tabs.Tab>
        </Tabs.List>
        <Tabs.Panel value="overview-1">Overview content</Tabs.Panel>
        <Tabs.Panel value="features-1">Features content</Tabs.Panel>
        <Tabs.Panel value="pricing-1">Pricing content</Tabs.Panel>
      </Tabs.Root>
    </Box>
  )
}
```


## Orientation

Use the `orientation` prop to render tabs vertically. The `indicatorPlacement` prop can be set to "start" (it defaults to "end").

}>
```tsx title="Vertical tabs demo"



export function VerticalTabsPreview() {
  return (
    <Box w="full">
      <Tabs.Root
        defaultValue="overview"
        orientation="vertical"
        indicatorPlacement="start"
      >
        <Tabs.List>
          <Tabs.Tab value="overview">Overview</Tabs.Tab>
          <Tabs.Tab value="features">Features</Tabs.Tab>
          <Tabs.Tab value="pricing">Pricing</Tabs.Tab>
        </Tabs.List>
        <Tabs.Panel value="overview">Overview content</Tabs.Panel>
        <Tabs.Panel value="features">Features content</Tabs.Panel>
        <Tabs.Panel value="pricing">Pricing content</Tabs.Panel>
      </Tabs.Root>
    </Box>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the tabs.

| Component     | Description                             |
| ------------- | --------------------------------------- |
| TabsRoot      | The context provider for the tabs parts |
| TabsList      | The list container of the tabs          |
| TabsTrigger   | The tab components of the tabs          |
| TabsIndicator | The indicator of the active tabs state  |
| TabsContent   | The panel container for the tabs.       |

}>
```tsx title="Custom tabs demo"



function CustomTabsPreview() {
const tabData = [
{
id: 'asphodel',
label: 'Asphodel',
content: 'A peaceful and quiet region of the underworld.',
},
{
id: 'elysium',
label: 'Elysium',
content: 'A paradise for the souls of the heroic and the virtuous.',
},
{
id: 'tartarus',
label: 'Tartarus',
content: 'A deep abyss used as a dungeon of torment and suffering.',
},
]

return (
<Box w="1/2">
<Tabs.Root defaultValue="asphodel">
<Tabs.List
css={{
            bgColor: 'page.surface.200',
            borderBottom: 'none',
            rounded: 'md',
            '& > :is([data-part=indicator])': {
              bgColor: 'danger.surface.initial',
              h: 'var(--height)',
              rounded: 'md',
              zIndex: 'base',
            },
          }} >
{tabData.map((tab) => (
<Tabs.Tab
css={{
                zIndex: 'decorator',
                _selected: {
                  color: 'danger.text.100',
                },
                _after: {
                  display: 'none',
                },
              }}
key={tab.id}
value={tab.value} >
{tab.label}
</Tabs.Tab>
))}
</Tabs.List>

        <For each={tabData}>
          {(tab) => (
            <Tabs.Panel
              key={tab.id}
              value={tab.value}
              css={{
                paddingBlock: 'md',
              }}
            >
              {tab.content}
            </Tabs.Panel>
          )}
        </For>
      </Tabs.Root>
    </Box>

)
}

```


## API

### Props

The `Tabs` component is an abstraction of the primitives and accepts the following props:

| Name               | Default      | Description                                                                                                                                                                   |
| ------------------ | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| palette            | `action`     | The color palette of the tabs                                                                                                                                                 |
| orientation        | `horizontal` | The orientation of the group.                                                                                                                                                 |
| indicatorPlacement | `end`        | The position of the active tab indicator. Placement follows the `orientation` flow: `start` renders at the start edge (top or left), `end` at the end edge (bottom or right). |

The `Tabs.Root` component also accepts all the props of the [`TabsRoot` primitive props](https://ark-ui.com/react/docs/components/tabs#api-reference)

#### Tabs component parts

The `Tabs` API is an Object containing the full family of abstracted components.

> **Note:** Although the Tabs API is similar to the TabsParts, it returns abstractions of the primitives. The TabsParts return the primitives only.

| Name  | Description                                           |
| ----- | ----------------------------------------------------- |
| Root  | An abstraction of the `TabsRoot`.                     |
| List  | An abstraction of the `TabsList` and `TabsIndicator`. |
| Tab   | An abstraction of the `TabsTrigger`.                  |
| Panel | An abstraction of the `TabsContent`.                  |

### Parts

The `TabsParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the TabsParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name      | Description                                                             |
| --------- | ----------------------------------------------------------------------- |
| Root      | The `TabsRoot` component which is the Provider for the family.          |
| List      | The `TabsList` component which is the container for the tabs.           |
| Trigger   | The `TabsTrigger` component which is the tab component.                 |
| Content   | The `TabsContent` component which is the panel container.               |
| Indicator | The `TabsIndicator` component which displays based on the active state. |
```


---
## tag

---
title: 'Tag'
description: 'Used for categorizing or labeling content'
npm: '@cerberus-design/react'
source: 'components/tag'
recipe: 'tag.ts'
---








```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

You can mix and match all of the examples to create the tag style of your choosing.


```tsx




export function BasicDemo() {
  return (
    <HStack gap="md">
      <Tag>Filled</Tag>
      <Tag>
        <Information />
        Start icon
      </Tag>
      <Tag>
        End icon
        <Information />
      </Tag>
    </HStack>
  )
}
```


## Usage Variants

Use the `usage` prop to change the style of the tag.


```tsx
// Source available in static configuration: {DEMOS.usageMeta}
```

<br />

```tsx




export function UsageDemo() {
  return (
    <HStack gap="md">
      <For each={tagUsages}>
        {(usage) => (
          <Tag key={usage} usage={usage}>
            {usage}
          </Tag>
        )}
      </For>
    </HStack>
  )
}
```


## Shape Variants

Use the `shape` prop to change the shape of the tag.


```tsx
// Source available in static configuration: {DEMOS.shapesMeta}
```

<br />

```tsx




export function ShapeDemo() {
  return (
    <HStack gap="md">
      <For each={tagShapes}>
        {(shape) => (
          <Tag key={shape} shape={shape}>
            {shape}
          </Tag>
        )}
      </For>
    </HStack>
  )
}
```


## Colors

You can set the color of the tag by using the `palette` prop.

> **Note:** By nature of CSS rules, only a `palette` or `gradient` can be used at a time. This is because the `palette` prop sets the background color, and the `gradient` prop sets the background gradient.


```tsx
// Source available in static configuration: {DEMOS.paletteMeta}
```

<br />

```tsx






const COLOR_LIST = tagPalettes.map((palette) => ({ palette, variants }))

export function PaletteDemo() {
  return (
    <Grid columns={5} gap="md" px="lg" w="full">
      {COLOR_LIST.map(({ palette, variants }) => (
        <Fragment key={`${palette}`}>
          <Text as="small">{palette}:</Text>
          {variants.map(({ usage, shape }) => (
            <GridItem key={`${palette}:${usage}:${shape}`} colSpan={1}>
              <Tag palette={palette} usage={usage} shape={shape}>
                <Information />
                Label
              </Tag>
            </GridItem>
          ))}
        </Fragment>
      ))}
    </Grid>
  )
}
```


## Gradients

You can set the gradient of the tag by using the `gradient` prop.

> **Note:** By nature of CSS rules, only a `palette` or `gradient` can be used at a time. This is because the `palette` prop sets the background color, and the `gradient` prop sets the background gradient.


```tsx






const GRAD_LIST = tagGradients.map((gradient) => ({ gradient, variants }))

export function GradientDemo() {
  return (
    <Grid columns={5} gap="md" px="lg" w="full">
      {GRAD_LIST.map(({ gradient, variants }) => (
        <Fragment key={`${gradient}`}>
          <Text as="small">{gradient}:</Text>
          {variants.map(({ usage, shape }, idx) => (
            <GridItem key={`${gradient}-${idx}`} colSpan={1}>
              <Tag gradient={gradient} usage={usage} shape={shape}>
                <Information />
                Label
              </Tag>
            </GridItem>
          ))}
        </Fragment>
      ))}
    </Grid>
  )
}
```


## Closable

To use a closable tag, just pass an `onClick` prop to the `Tag` component. This will create a pill-shaped tag with a close icon button.


```tsx
'use client'




export function ClosableDemo() {
  const handleClick = () => {
    console.log('Clicked!')
  }

  return (
    <HStack gap="md">
      <Tag onClick={handleClick}>Closable</Tag>

      <Tag palette="info" onClick={handleClick}>
        Closable
      </Tag>

      <Tag palette="danger" onClick={handleClick}>
        Closable
      </Tag>
    </HStack>
  )
}
```


## Customizing

You can customize the `Tag` using style props and data selectors on any slot primitve.


```tsx


export function CustomDemo() {
  return (
    <Tag colorPalette="danger" p="2" rounded="0!" transform="skew(-10deg)">
      Cerberus Forever
    </Tag>
  )
}
```


## Primitives

You can customize the tag by utilizing style props and primitives. A Closable Tag is just a Tag with an IconButton inside.

| Component | Description                  |
| --------- | ---------------------------- |
| TagRoot   | The root wrapper of the tag. |

### Data Attributes

The Primitives additionally use the following data attributes for custom styling:

| Name           | Value          | Description                   |
| -------------- | -------------- | ----------------------------- |
| `data-scope`   | `tag`          | The scope of the components.  |
| `data-part`    | `root`         | The root wrapper of the tag.  |
| `data-palette` | _palette name_ | The color palette of the tag. |

## API

### Props

The `Tag` component is an abstraction of the primitives and accepts the following props:

| Name     | Default     | Description                                        |
| -------- | ----------- | -------------------------------------------------- |
| gradient | `undefined` | The gradient of the tag (overrides palette).       |
| palette  | `page`      | The color palette of the tag (overrides gradient). |
| usage    | `filled`    | The style treatment of the tag.                    |
| shape    | `pill`      | The shape of the tag.                              |
| onClick  | `undefined` | How to create a Closable tag.                      |


---
## testing

---
---



## Testing

<strong>Best Practices for Testing React Components using Vitest and Jest</strong>

<NoteAdmonition description={<>In general, we recommend using <a href="https://vitest.dev/" target="_blank" rel="norefferrer">Vitest</a> over
 <a href="https://jestjs.io/" target="_blank" rel="norefferrer">Jest</a> but the setup are similar.</>} />

Before writing tests, ensure your project has the necessary dependencies:

```sh
npm install --save-dev vitest jsdom @testing-library/dom @testing-library/jest-dom @testing-library/react @testing-library/user-event
```

## Configuration

Create the `vite.config.ts` file to configure Vitest.

```ts


export default defineConfig({
  // ...
  test: {
    globals: true,
    environment: "jsdom",
    setupFiles: "./setup-test.ts",
  },
})
```

Setting `globals: true` will automatically import the Vitest globals and removes
the need to import `expect`, `test`, `describe`, etc.

## Setup Test File

Create the `setup-test.ts` file to configure the testing environment and mock
unimplemented APIs.

Here's a common example for Cerberus projects:

```ts title="setup-test.ts"
import "@testing-library/jest-dom/vitest"



import "vitest-axe/extend-expect"

const { window } = new JSDOM()

// ResizeObserver mock
vi.stubGlobal("ResizeObserver", ResizeObserver)
window["ResizeObserver"] = ResizeObserver

// IntersectionObserver mock
const IntersectionObserverMock = vi.fn(() => ({
  disconnect: vi.fn(),
  observe: vi.fn(),
  takeRecords: vi.fn(),
  unobserve: vi.fn(),
}))
vi.stubGlobal("IntersectionObserver", IntersectionObserverMock)
window["IntersectionObserver"] = IntersectionObserverMock

// Scroll Methods mock
window.Element.prototype.scrollTo = () => {}
window.Element.prototype.scrollIntoView = () => {}

// requestAnimationFrame mock
window.requestAnimationFrame = (cb) => setTimeout(cb, 1000 / 60)

// URL object mock
window.URL.createObjectURL = () => "https://i.pravatar.cc/300"
window.URL.revokeObjectURL = () => {}

// navigator mock
Object.defineProperty(window, "navigator", {
  value: {
    clipboard: {
      writeText: vi.fn(),
    },
  },
})

// Override globalThis
Object.assign(global, { window, document: window.document })
```

## Custom Render

First, you need to create a custom render function to wrap your component in the
CerberusProvider.

```tsx title="test-utils/render.tsx"

import {
  CerberusProvider,
  defineIcons,
  makeSystemConfig,
  NotificationCenter,
} from '@cerberus/react'

const config = makeSystemConfig({
  icons: defineIcons({
    // Define your icons here
    // Example: "home": <svg>...</svg>
  }),
})

export function render(ui: ReactNode) {
  return rtlRender(<>{ui}</>, {
    wrapper: (props: PropsWithChildren) => (
      <CerberusProvider config={config}>
        {props.children}
        <NotificationCenter />
      </CerberusProvider>
    ),
  })
}
```

## Testing Components

Now, you can use the `render` function to test your components.

```tsx title="testing/render.tsx"



test("renders a button", () => {
  render(<Button>Click me</Button>)
  expect(screen.getByText("Click me")).toBeInTheDocument()
})
```


---
## text

---
title: 'Text'
description: 'A component for rendering text.'
npm: '@cerberus-design/react'
source: 'components/text'
---




```ts

```

## Usage

}>
```tsx title="Basic usage"


function TextDemo() {
  return (
    <>
      <Text
        as="h1"
        color="page.text.100"
        textStyle={{
          base: 'heading-md',
          md: 'heading-lg',
        }}
      >
        Hello, world!
      </Text>
      <Text>This is normal text</Text>
      <Text as="small" color="info.text.100" textStyle="body-sm">
        This is small text
      </Text>
    </>
  )
}
```


## Raw HTML

To render raw HTML, you can utilize the React `dangerouslySetInnerHTML` combined with the `whiteSpace` property.

}>
```tsx title="Basic usage"


function DangerouslySetDemo() {
  const rawHTML =
    '<p>This is a raw paragraph with a <strong>bold</strong> word and a <br /> line break.</p>'

  return (
    <Text
      dangerouslySetInnerHTML={{
        __html: rawHTML,
      }}
      textStyle="body-sm"
      whiteSpace="pre-wrap"
    />
  )
}
```


## API

```ts showLineNumbers=false
export type Headings = 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
export type TextElements = 'p' | 'strong' | 'em' | 'small' | 'span'

export interface TextProps extends BoxProps {
  as?: TextElements | Headings
}

define function Text(props: TextProps): ReactNode
```

### Props

The `Text` component accepts the following props along with the props from the `Box` component.

| Name     | Default | Description                                                   |
| -------- | ------- | ------------------------------------------------------------- |
| as     |    | The text-based element to render the component as. |


---
## textarea

---
title: Textarea
description: The Textarea component displays a textarea field.
npm: '@cerberus-design/react'
source: 'components/field'
recipe: 'slots/field.ts'
ark: 'field'
---







```ts
import {
  Field,
  Textarea,
} from '@cerberus/react'
```

## Usage

The `Textarea` component displays a textarea field.

}>
```tsx title="some-form.tsx" {39}



export function BasicFieldPreview() {
  return (
    <form action={someAction} method="post">
      <Box w="1/2">
        <VStack alignItems="flex-start" gap="lg" w="full">
          <Field
            ids={{
              control: 'email',
            }}
            label="Enter your email"
            helperText="We'll never share your email with anyone else."
            required
          >
            <Input name="email" type="email" />
          </Field>
          <Field
            ids={{
              control: 'invalid-name',
            }}
            label="Invalid example"
            helperText="This is an example of an invalid field."
            errorText="A name is required to submit this form. It replaces the helper text."
            invalid
            required
          >
            <Input name="invalid-name" type="text" />
          </Field>
          <Field
            ids={{
              control: 'message',
            }}
            label="Anything else you want to tell us?"
            helperText="This will help us learn more about you."
            secondaryHelperText="0/300"
          >
            <Textarea name="message" />
          </Field>
        </VStack>
      </Box>
    </form>
  )
}
```


## Secondary Helper Text

The `Textarea` component supports secondary helper text, which can be used to display additional information or a character count.
}>
```tsx title="secondary helper text demo"
<Field
  label="Anything else you want to tell us?"
  secondaryHelperText="0/300"
>
  <Textarea name="secondary_text" />
</Field>
```


## Customizing

You can customize the textarea by passing styles directly into the component. Textarea is a re-export of the `FieldTextarea` primitive.

}>
```tsx {18-20} title="custom textarea demo"



export function CustomField() {
  return (
    <Box w="1/2">
      <FieldParts.Root ids={{ control: 'customField' }}>
        <FieldParts.Label
          css={{
            fontSize: 'xl',
            fontWeight: 'black',
            textTransform: 'uppercase',
          }}
        >
          Custom Label
        </FieldParts.Label>
        <FieldParts.Textarea
          css={{
            transform: 'skewX(-10deg)',
          }}
        />
        <FieldParts.HelperText
          css={{
            fontStyle: 'italic',
          }}
        >
          Custom Helper Text
        </FieldParts.HelperText>
      </FieldParts.Root>
    </Box>
  )
}
```



## API

### Props

The `Textarea` accepts the following props in addition to any native `textarea` props:

| Name     | Default | Description                            |
| -------- | ------- | -------------------------------------- |
| size     |  | This size variant of the textarea |

The `Textarea` component also accepts any of the props from the [`FieldParts.Textarea` primitive](https://ark-ui.com/react/docs/components/field#api-reference).


---
## theme

---
title: Theme
description: Used to force a part of the tree to a different mode or theme.
npm: '@cerberus-design/react'
source: 'components/theme'
---




## Usage

```tsx

```

```tsx
<Theme mode="dark">
  This is dark mode
</Theme>
```

## Examples

### Basic

}>
```tsx title="Basic example"



function BasicExample() {
  return (
    <VStack alignItems="flex-start" w="3/4">
      <Box w="full">
        <Button>Default</Button>
      </Box>

      <Theme mode="light" css={{ w: 'full' }}>
        <Box bgColor="page.bg.200" p="md" w="full">
          <Button>Light</Button>
        </Box>
      </Theme>

      <Theme mode="dark" css={{ w: 'full' }}>
        <Box bgColor="page.bg.200" p="md" w="full">
          <Button>Dark</Button>
        </Box>
      </Theme>

      <Theme mode="system" css={{ w: 'full' }}>
        <Box bgColor="page.bg.200" p="md" w="full">
          <Button>System</Button>
        </Box>
      </Theme>

      <Theme mode="dark" theme="acheron" css={{ w: 'full' }}>
        <Box bgColor="page.bg.200" p="md" w="full">
          <Button>Dark Acheron</Button>
        </Box>
      </Theme>
    </VStack>
  )
}
```


### Nested

The theme can be nested to apply different appearances to different parts of the
tree. This is useful for applying a global appearance and then overriding some
parts of it.

> Good to know: We use native panda-css attributes to achieve this.

}>
```tsx title="Nested example"



function NestedExample() {
  return (
    <Theme mode="dark" css={{ w: 'full' }}>
      <Box bgColor="page.bg.200" p="md" w="full">
        <Button css={{ mb: 'md' }}>Dark</Button>
        <Theme mode="light" css={{ w: 'full' }}>
          <Box bgColor="page.bg.200" p="md" w="full">
            <Button>Light</Button>
          </Box>
        </Theme>
      </Box>
    </Theme>
  )
}
```


### Portalled

Use the `asChild` prop to force the appearance of portalled elements like the
popover and modal content.

```tsx title="Portalled example" {12-18}



function PortalledExample() {
  return (
      <TooltipParts.Root>
      <TooltipParts.Trigger asChild>
        <Button>Dark</Button>
      </TooltipParts.Trigger>

      <TooltipParts.Positioner>
        <TooltipParts.Content asChild>
          <Theme mode="dark">
            <Box bgColor="page.bg.200" p="md" w="full">
              This is a dark mode tooltip bubble
            </Box>
          </Theme>
        </TooltipParts.Content>
      </TooltipParts.Positioner>
    </TooltipParts.Root>
  )
}
```

### Page Specific Color Mode

To lock a page to a specific color mode (light or dark), wrap the entire page
with the `Theme` component.

```tsx title="page.tsx"


export default Page = ({ children }) => {
  return (
    <Theme mode="dark">{/* Rest of the page */}</Theme>
  )
}
```


---
## toggle

---
title: 'Toggle'
description: 'Toggle allows users to toggle between states via an action.'
npm: '@cerberus-design/react'
source: 'components/toggle'
ark: 'toggle'
---

import {
  WhenNotToUseAdmonition,
  NoteAdmonition,
} from '@/app/components/Admonition'



The `Toggle` component is a two-state button that allows users to toggle between states via an action.

> **Note:** If you need to conditionally render content based on a binary condition, use the Show component.

```ts

```

## Usage

The Toggle component is unstyled to fit any scenario you may need.

}>
```tsx title="notification-toggle.tsx"



export default function BasicPreview() {
  return (
    <ToggleParts.Root defaultPressed={true} asChild>
      <IconButton ariaLabel="Notification preferences">
        <ToggleParts.Indicator fallback={<NotificationOff />}>
          <Notification />
        </ToggleParts.Indicator>
      </IconButton>
    </ToggleParts.Root>
  )
}
```


## Primitives

You can utilize the primitive components or the `css` prop to customize the toggle.

| Component | Description |
| --------- | ----------- |
| ToggleRoot    | The context provider for the Toggle parts |
| ToggleIndicator   | The indicator shown based on the toggle state |

## API

### Parts

The `ToggleParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the ToggleParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name     | Description                            |
| -------- | -------------------------------------- |
| Root     | The `ToggleRoot` component which is the Provider for the family. |
| Indicator  | The `ToggleIndicator` component which displays based on the pressed state. |


---
## tooltip

---
title: Tooltip
description: A small pop-up box that appears when a user hovers over an element.
npm: '@cerberus-design/react'
source: 'components/tooltip'
recipe: 'slots/tooltip.ts'
ark: 'tooltip'
---



import {
  BasicTooltipPreview,
  PositioningTooltipPreview,
} from '../components/tooltip/static'

```ts

```

## Usage

}>
```tsx
'use client'




function BasicTooltipPreview() {
return (

<Tooltip
      content="Get information from something that has a very long description."
    >
<Information />
</Tooltip>
)
}

````


## Positioning

You can position the tooltip relative to the target element using the `position` prop.

}>
```tsx title="Positioning Demo"
'use client'





function PositioningTooltipPreview() {
  return (
    <HStack gap="3xl">
      <Tooltip
        content="Top position"
        positioning={{
          placement: 'top',
        }}
      >
        <InformationFilled />
      </Tooltip>
      <Tooltip
        content="Right position"
        positioning={{
          placement: 'right',
        }}
      >
        <InformationFilled />
      </Tooltip>
      <Tooltip
        content="Bottom position"
        positioning={{
          placement: 'bottom',
        }}
      >
        <InformationFilled />
      </Tooltip>
      <Tooltip
        content="Left position"
        positioning={{
          placement: 'left',
        }}
      >
        <InformationFilled />
      </Tooltip>
    </HStack>
  )
}
````



## Primitives

You can utilize the primitive components or the `css` prop to customize the checkbox.

| Component         | Description                                              |
| ----------------- | -------------------------------------------------------- |
| TooltipRoot       | The context provider for the Tooltip parts               |
| TooltipTrigger    | The focusable element that triggers the tooltip on hover |
| TooltipPositioner | The positioning container for the tooltip                |
| TooltipContent    | The content of the tooltip                               |
| TooltipArrow      | The arrow container of the tooltip bubble                |
| TooltipArrowTip   | The tip of the arrow                                     |

## API

### Props

The `Tooltip` component is an abstraction of the primitives and accepts the following props:

| Name    | Default | Description                                         |
| ------- | ------- | --------------------------------------------------- |
| content |         | What to display in the Tooltip.                     |
| portal  | `false` | When true, renders the `content` within a `Portal`. |

The `Tooltip` component also accepts all the props of the [`TooltipRoot` primitive props](https://ark-ui.com/react/docs/components/tooltip#api-reference)

### Parts

The `TooltipParts` API is an Object containing the full family of components.

> **Note:** It is best to only use the TooltipParts if you are building a custom solution. Importing Object based components will ship every property it includes into your bundle, regardless if you use it or not.

| Name       | Description                        |
| ---------- | ---------------------------------- |
| Root       | The `TooltipRoot` component.       |
| Trigger    | The `TooltipTrigger` component.    |
| Positioner | The `TooltipPositioner` component. |
| Content    | The `TooltipContent` component.    |
| Arrow      | The `TooltipArrow` component.      |
| ArrowTip   | The `TooltipArrowTip` component.   |


---
## wrap

---
title: Wrap
description: Used to add space between elements and wraps automatically if there isn't
  enough space.
panda: https://panda-css.com/docs/concepts/patterns#wrap
---






```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

By default, `Wrap` applies `display: flex`, `flex-wrap: wrap`, and `gap: 8px` to
its children.


```tsx



export function BasicDemo() {
  return (
    <Wrap w="3/4">
      <DecorativeBox h="20" />
      <DecorativeBox h="20" w="calc(50% - 4px)" />
      <DecorativeBox h="20" w="calc(50% - 4px)" />
    </Wrap>
  )
}
```


### Gap or Spacing

Pass the `gap` prop to apply a consistent spacing between each child, even if it
wraps.


```tsx



export function GapDemo() {
  return (
    <Wrap gap="5" w="3/4">
      {Array.from({ length: 12 }).map((_, index) => (
        <DecorativeBox key={index} h="12" w="12" />
      ))}
    </Wrap>
  )
}
```


### Alignment

Pass the `align` prop to change the alignment of the child along the cross axis.


```tsx



export function AlignDemo() {
  return (
    <Wrap align="center" gap="md" w="3/4">
      {Array.from({ length: 5 }).map((_, index) => (
        <DecorativeBox key={index} h="80px" w="180px">
          Box {index + 1}
        </DecorativeBox>
      ))}
    </Wrap>
  )
}
```


### Justify

Pass the `justify` prop to change the alignment of the child along the main
axis.


```tsx



export function JustifyDemo() {
  return (
    <Wrap justify="center" gap="md" w="3/4">
      {Array.from({ length: 5 }).map((_, index) => (
        <DecorativeBox key={index} h="80px" w="180px">
          Box {index + 1}
        </DecorativeBox>
      ))}
    </Wrap>
  )
}
```


### Row and Column Gap

Pass the `rowGap` and `columnGap` props to apply a consistent spacing between
the rows and columns.


```tsx
Example not found
```


## Props

| Prop        | Type                               | Description          |
| ----------- | ---------------------------------- | -------------------- |
| `rowGap`    | `number \| string`                 | Gap between rows     |
| `columnGap` | `number \| string`                 | Gap between columns  |
| `justify`   | `CSSProperties['justify-content']` | Justify content      |
| `gap`       | `number \| string`                 | Gap between children |


---
## api

---
title: Data Grid API
description: The API reference for the Data Grid component.
package: 'data-grid'
---



## API

The Data Grid API provides the following props:

| Params         | Required | Description                                                    |
| -------------- | -------- | -------------------------------------------------------------- |
| `data`         | `true`   | The full set of data to display in the grid.                   |
| `columns`      | `true`   | The list of defined columns using the column helper.           |
| `initialState` | `false`  | The initial state of the grid for pagination settings.         |
| `rowSize`      | `false`  | The size of each row in pixels or one of the predefined sizes. |
| `toolbar`      | `false`  | The component to render in the grid toolbar slot.              |
| `overlays`     | `false`  | Optional overlays to render within the viewport.               |
| `footer`       | `false`  | The component to render in the grid footer slot.               |
| `theme`        | `false`  | Custom style options to apply to the grid layout.              |

### Overlay Slots

The `overlays` prop expects an Object of the following optional properties in the table below. Each property expects a `ReactNode` value:

| Name        | Description                                                                                                     |
| ----------- | --------------------------------------------------------------------------------------------------------------- |
| `noContent` | Displays when there are no rows present in the data or if the data has filtered out all rows to an empty state. |
| `pending`   | Displays when the data grid is still loading.                                                                   |
| `initial`   | Displays when the data grid has finished the initial pending phase.                                             |

## Slot Attributes

Each slot layer is assigned a unique `data-part` attribute for styling and targeting
specific slot layers.

| Name         | Value       | Description                          |
| ------------ | ----------- | ------------------------------------ |
| `data-scope` | `data-grid` | The scope of the components.         |
| `data-part`  | `toolbar`   | The container of the toolbar slot.   |
| `data-part`  | `root`      | The container Data Grid family.      |
| `data-part`  | `viewport`  | The container of the viewport slot.  |
| `data-part`  | `head-cell` | The container of the head cell slot. |
| `data-part`  | `row`       | The container of the row slot.       |
| `data-part`  | `row-cell`  | The container of the row cell slot.  |
| `data-part`  | `footer`    | The container of the footer slot.    |

> **Note:** Any other slot part displayed in the Grid is inherited from the Cerberus React component API for that item.


---
## columns

---
title: Data Grid Columns
description: Learn about building columns in the Data Grid component.
package: 'data-grid'
---





## Overview

Column definitions are the **foundational building blocks** of the Data Grid component.
They define the structure and appearance of each column, including its label,
data type, and formatting options. This creates a data-driven single source of truth
for the grid's visual representation.

Thus, the `DataGrid` component is essentially just a layout container that simply
renders column definitions. It passes the state of the column to the `cell`
property which is what renders the actual content of each cell.

Each column has the ability to opt-in to features listed in the Features section.

### The Role of Columns

Since the Data Grid is Signal driven, it is important to understand that column
definitions are meant to be **static and immutable**.

When you need dynamic column behavior, that should be handled within the component
being rendered by the `cell` property.

All of our examples have column definitions that can be found in the source code by
clicking the "Edit this page" link on the right sidebar.

## Column Definitions

There are three types of column definitions:

1. [Display](#display-columns)
2. [Accessor](#accessor-columns)
3. [Accessor Function](#accessor-function-columns)

All column definitions can display custom content using the `cell` property.
This allows you to customize the visual output appearance of each cell content.

### Display Columns

Display columns are used to render **static columns** that do not utilize
data-driven column features (e.g., filtering or sorting).


```tsx
Example not found
```


| Params  | Type                    | Required |
| ------- | ----------------------- | -------- |
| options | `DisplayOptions<TData>` | true     |

> **Note:** Due to their static nature, display columns only allow the pinning feature.

### Accessor Columns

Accessor columns are used to render data that is directly related to the data source
and utilize all features.


```tsx
Example not found
```


| Params  | Type                                   | Required |
| ------- | -------------------------------------- | -------- |
| key     | `string`                               | true     |
| options | `AccessorOptions<TData, TValue[TKey]>` | true     |

### Accessor Function Columns

Accessor function columns are used to render data that is derived from the data source.
They are typically used to display low-level customization like aggregating data or
performing complex calculations.


```tsx
Example not found
```


| Params     | Type                             | Required |
| ---------- | -------------------------------- | -------- |
| accessorFn | `(data: TData) => TValue`        | true     |
| options    | `AccessorOptions<TData, TValue>` | true     |

## Shared Column Options

Both Display and Accessor columns share the following options:

| Params     | Type                         | Required | Description                                                                                                                                                                               |
| ---------- | ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`       | `string`                     | true     | Unique identifier for the column                                                                                                                                                          |
| `header`   | `string/Fn`                  | true     | Header text or function to generate header text                                                                                                                                           |
| `accessor` | `Fn`                         | true     | Accessor function or key to access data                                                                                                                                                   |
| `minWidth` | `number`                     | false    | Minimum width of the column. **Ensure your column width is large enough to fit all features and content**                                                                                 |
| `width`    | `number`                     | false    | Strict width of the column. Omitting this will render a flexed column. Adding this will override all widths. **Ensure your column width is large enough to fit all features and content** |
| `maxWidth` | `number`                     | false    | Maximum width of the column. **Ensure your column width is large enough to fit all features and content**                                                                                 |
| `features` | `Feature[]`                  | false    | Array of features to enable on the column                                                                                                                                                 |
| `cell`     | `CellOptions<TData, TValue>` | false    | Options for rendering the cell. Not providing this will render a string.                                                                                                                  |


---
## context

---
title: Data Grid Context
description: A signal-driven store for reading and updating state in a highly performant way.
package: 'data-grid'
---








```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Overview

The Data Grid runs on a **signal-driven** store for reading and updating state in a
highly performant way. This allows the grid to bypass React's internal reactivity
system, preventing unnecessary re-renders and improving overall performance by
manaing state outside of the scope of React components.

To learn more about signals and how they work, see the [Signals documentation](https://cerberus.digitalu.design/docs/signals/overview).

## Using the context

To recieve the context from the Data Grid, you simply use the `useDataGridContext` hook
like you would any other hook in React.


```tsx
Example not found
```


## Reading Signals

When reading signals values from the context, you need to use them in a way that will
ensure the **reactivity is being tracked** via the `useRead` hook from the Cerberus
Signals library.

This will subscribe to the signal's reactivity and provide the latest value when
used within a component.

> **Note:** Accessing a context value without using the mentioned hook will not be reactive.


```tsx
Example not found
```


## Using Actions

Since actions only write changes, you can use them directly from the store.


```tsx
Example not found
```


## Store Reference

The Data Grid store provides both getter and setter helpers for accessing and updating state
in a signal-based reactive manner:

### Reactive Values

| Name                   | Type                                       | Description                                                    |
| ---------------------- | ------------------------------------------ | -------------------------------------------------------------- |
| `columns`              | `Accessor<InternalColumn<TData>[]>`        | A list of processed columns.                                   |
| `orderedColumns`       | `Accessor<InternalColumn<TData>[]>`        | A list of ordered columns.                                     |
| `rows`                 | `Accessor<TData[]>`                        | A list of processed rows.                                      |
| `rowSize`              | `Accessor<number>`                         | The height of the row.                                         |
| `rowCount`             | `Accessor<number>`                         | The current number of rows in the grid.                        |
| `allColsHidden`        | `Accessor<boolean>`                        | Whether all columns are hidden. Created via a computation.     |
| `totalHiddenCols`      | `Accessor<number>`                         | The total number of hidden columns.                            |
| `hiddenColsMaxReached` | `Accessor<boolean>`                        | Whether the maximum number of hidden columns has been reached. |
| `pageIndex`            | `Accessor<number>`                         | The current page index of the grid.                            |
| `pageSize`             | `Accessor<number>`                         | The current page size of the grid.                             |
| `pageRange`            | `Accessor<number[]>`                       | The page range options of the grid.                            |
| `currentPageRange`     | `Accessor<{ start: number; end: number }>` | The current page range.                                        |
| `pageCount`            | `Accessor<number>`                         | The current page count of the grid used for SSR pagination.    |
| `isServerPaginated`    | `Accessor<boolean>`                        | If pagination is using server-based.                           |
| `showColFilter`        | `Accessor<boolean>`                        | If the user has chosen the column filter feature option.       |
| `globalFilter`         | `Accessor<BaseFilterState>`                | The current global filter value used for column filtering.     |
| `colFilters`           | `Accessor<ColumnFilterState>`              | The current column filters used.                               |
| `filteredRows`         | `Accessor<TData[]>`                        | The rows after filtering.                                      |
| `sorting`              | `Accessor<SortState[]>`                    | The current sorting state of the grid.                         |
| `sortedRows`           | `Accessor<TData[]>`                        | The rows after sorting.                                        |
| `showManage`           | `Accessor<boolean>`                        | If the manage columns menu is open.                            |
| `phase`                | `Accessor<Phase>`                          | The current phase of the grid layout.                          |
| `pending`              | `Accessor<boolean>`                        | The state of the `pending` prop of the Data Grid.              |
| `hasSkeleton`          | `Accessor<boolean>`                        | If a skeleton overlay option is provided.                      |
| `rootCssVars`          | `Accessor<Record<string, string>>`         | The current CSS variables for the grid root element.           |
| `totalWidth`           | `Accessor<number>`                         | The total width of the grid (used for pinning).                |
| `visibleRows`          | `Accessor<TData[]>`                        | The list of visible rows in the viewport.                      |

### Actions

| Name                | Type                                                                 | Description                                 |
| ------------------- | -------------------------------------------------------------------- | ------------------------------------------- |
| `resizeColumn`      | `(columnId: string, delta: number) => void`                          | Resizes a column by updating its width.     |
| `setContainerWidth` | `Setter<number>`                                                     | Updates the width of the grid container.    |
| `setPage`           | `(details: PageDetails) => void`                                     | Updates the current page of the grid.       |
| `setPageIndex`      | `Setter<number>`                                                     | Updates the current page index of the grid. |
| `setPageSize`       | `(size: number) => void`                                             | Updates the page size of the grid.          |
| `setGlobalFilter`   | `Setter<BaseFilterState>`                                            | Updates the global filter value.            |
| `setColFilter`      | `Setter<ColumnFilterState>`                                          | Updates the col filter value.               |
| `setShowColFilter`  | `Setter<boolean>`                                                    | Updates the showColFilter value.            |
| `setShowManage`     | `Setter<boolean>`                                                    | Updates the showManage value.               |
| `setSort`           | `(colId: string, direction: SortDirection, multi?: boolean) => void` | Updates the sorting state of the grid.      |
| `toggleSort`        | `(colId: string, multi?: boolean) => void`                           | Toggles the sort direction of a column.     |
| `togglePinned`      | `(colId: string, state: PinnedState) => void`                        | Toggles the pinned state of a column.       |
| `updateData`        | `(data: TData[]) => void`                                            | Updates the grid data.                      |
| `updatePending`     | `(newState: boolean) => void`                                        | Updates the pending state.                  |


---
## dimensions

---
title: Dimensions
description: Learn how to control the dimensions of the Data Grid component.
package: 'data-grid'
---





## Overview

The Data Grid has no intrinsic dimensions: **you must set the dimensions or else 
it may not display correctly**. By default, the Data Grid fills the space of its 
parent container, so that container must have intrinsic dimensions. 

In other words, if the container has no child elements, then it still must have 
non-zero dimensions.

> **Note:** We highly recommend setting a height on any parent container to ensure virtualization is utilized. This will improve performance by limiting the number of elements rendered in the DOM.

## Flex Parent Container

The Data Grid can be placed inside a flex parent container like `VStack`, `Stack`, 
or `HStack`. Without setting a `height`, the Data Grid takes as much space as it 
needs to display all rows.

> **Note:** When using a flex container you gain the benefit of controlling the layout spacing via the gap property. See the Toolbar page for examples.


```tsx
Example not found
```


### Min and max height

The Data Grid will inherit the `minH` and `maxH` values from its parent container.
Using these would constrain the dimensions in the event of row quantities change.
Most of the time, setting a static `height` is sufficient enough.


```tsx
Example not found
```


### Percentage height

When using percentages (%) for height or width, make sure that the Data Grid's 
parent container has intrinsic dimensions. Browsers adjust the element based on 
a percentage of its parent's size. If the parent has no size, the percentage 
will be zero.

To put simply, an instrinsic height must be set on a parent in the DOM tree for
the Data Grid parent to have a non-zero size.

## Static Parent Container

Static parent containers follow the same rules as flex containers. The only difference
is that layout spacing must be controlled via the Toolbar or Footer components.

> **Note:** In the demo the Toolbar is adding margin bottom to itself to add spacing between itself and the Data Grid.


```tsx
Example not found
```


---
## filtering

---
title: Filtering
description: Learn about the filtering feature in the Data Grid component.
package: 'data-grid'
---





## Overview

Filtering allows users to view a subset of data based on criteria. There are
three ways for a user to filter:

1. **Single-column filtering**: Clicking the "Filter" option from the feature menu when the column has opted into filtering.
2. **Multi-column filtering**: Following option 1 for any additional column
3. **Global filtering**: Utilizing the `setGlobalFilter` action from the [Data Grid Context](/docs/data-grid/context).

**Active Actions**

Once a filter is active, the user can:

1. **Edit filters**: Clicking the added "Edit filter" icon button that displays in the column header that has the active filter.
2. **Clear filters**: Clicking the "Clear Filter" option in the column feature menu.


```tsx
Example not found
```


## Implementing column filtering

You must opt-in to column filtering by setting the `features.filter` prop to `true` or passing in a custom filter function. Doing so will display the filter option in the column menu.


```tsx
Example not found
```


## Multi-column Filtering

Multi-column filtering is enabled by default. The user simply selects another column to filter in addition to any other column that is actively filtered.

## Global Filtering

You can globally filter the Grid by utilizing the `setGlobalFilter` action in any slot component you provide.

In this example, we create a custom Toolbar that filters the grid globally on input.


```tsx
Example not found
```


## Custom Comparator

A comparator determines how two cell values should be filtered. The default comparator uses the vanilla JavaScript basic comparison from the [Operator](#operators) provided.

To provide a custom comparator, you can pass a function as the `features.filter` option.

The snippet below is the same comparator we are using for all the demos on this page.


```tsx
Example not found
```


### Operators

The Data Grid provides an `OPERATORS` constant which is used to ensure consistency across any filter-based approach you may use.


```tsx
Example not found
```


## Options

The `filter` feature accepts either a `boolean` or a custom filter function that provides the following arguments:

| Params        | Type      | Description                               |
| ------------- | --------- | ----------------------------------------- |
| `row`         | `TData`   | The row of the grid comparing the filter. |
| `columnId`    | `string`  | The columnId the filter is applied to.    |
| `filterValue` | `unknown` | The value provided to the filter.         |


---
## footer

---
title: Footer
description: Learn how to create custom footers in the Data Grid component.
package: 'data-grid'
---





## Overview

The Footer is a reserved area below the Data Grid component typically used for
information or global actions.

To add a custom footer, you can use the `footer` prop and pass a React component.

Since the footer is positioned within the Data Grid component, **it shares the same
height restrictions as the grid itself**. Ensure your parent height is set appropriately
to accommodate the footer.

<NoteAdmonition description="If you don't need the context of the grid, we recommended rendering your footer outside of the Data Grid component." />


```tsx
Example not found
```


## Grid Context

To access the Data Grid context, you use the `useDataGridContext` hook which provides
a signal driven store for reading and updating state in a highly performant way.

Read the [Data Grid Context](/docs/data-grid/context) documentation for more details.


---
## overlays

---
title: Overlays
description: Learn about the overlays for the Data Grid component.
package: 'data-grid'
---






## Overview

The Data Grid comes with placeholder content overlays that live within the contextual provider.
When provided, any component used for the overlay slot will have access to the Data Grid context
via the `useDataGridContext` hook.

You can utilize an overlay by adding the name of the slot as a property to the Data Grid `overlays` prop. Each overlay slot comes with a default fallback when no custom component is provided.

Overlay slots are placed within the grid viewport which is the body of the Data Grid

> **Note:** All overlays outside of the skeleton will lock the scroll. This includes custom pending overlay components.

## No Content

The `noContent` overlay appears when there are no rows to display in the Data Grid. This can be from providing an empty `data` Array or being filtered out via a feature or store action.


```tsx
Example not found
```


### Custom No Content

Pass a component to the `overlays.noContent` prop to display a custom overlay.

For convenience, the content is placed within a [`Center`](/docs/components/center) parent that matches the height of the viewport area.


```tsx
Example not found
```


## Pending

The `pending` overlay appears when the Data Grid `pending` prop is set to `true` to signify the Grid is in a loading state.

The Data Grid supports 3 loading overlay variants out of the box:

- **skeleton**: an animated placeholder of the Data Grid.
- **linear-progress**: an indeterminate linear progress bar.
- **circular-progress**: a circular loading spinner.

For convenience, the content is placed within an absolutely positioned [`Box`](/docs/components/box) parent that matches the height of the viewport area and sits above the row content.

### Skeleton

Pass `'skeleton'` to the `overlays.pending` prop to display a skeleton pending overlay.


```tsx
Example not found
```


### Linear

Pass `'linear'` to the `overlays.pending` prop to display a linear-progress pending overlay.


```tsx
Example not found
```


### Circular

Pass `'circular'` to the `overlays.pending` prop to display a circular-progress pending overlay.


```tsx
Example not found
```


### Custom Loading

Pass a component to the `overlays.loading` prop to display a custom overlay.


```tsx
Example not found
```


### Initial Loading

For initial loading states, you can use the `overlays.initialPending` prop to display a pending overlay.

This will render the value only during the mounting phase of the component. Once `data` has been populated for the first time, the `pending` overlay will be used from then on.

#### The Initial Pending Phase

The initial pending phase is determined by two conditions:

- The Data Grid is mounted for the first time.
- The `pending` prop is set to `true` for the first time.

Once these conditions are met, the `pending` overlay will be displayed from that point forward.


```tsx
Example not found
```


### Cell pending with Suspense

For cell level pending states, you can take advantage of `Suspense` to provide column-level loading states if Promises are used within the [Column Definition](/docs/data-grid/columns) cell.

This is a natural resource provided by React (and [Signals](/docs/signals/overview)) that _doesn't require any additional prop management on the Data Grid_.

> **Note:** If using mutations, you need to manually manage the loading state by omitting the Suspense component and instead using the loading prop from useMutation.

> _:bulb: "Wow! That was fast after the first click?!"_ <br /><br />Yup! The Cerberus signals lib caches querys. Since the state saves a string, the cache is smart enough to know that a string of "success" already exists. Thus, it bypasses the fetch. If the strings where unique (or the data more complex) it would handle it accordingly.


```tsx
Example not found
```


---
## overview

---
title: Data Grid Overview
description: A fast and extensible React data grid, with filtering, sorting, aggregation, and more.
package: 'data-grid'
---





## What is Data Grid?

The Data Grid is a React component built to provide a drop-in solution for displaying
data-heavy tables with features like filtering, sorting, pagination, and more. Our
execution is inspired by the ideaology of MUI's DataGrid component with the performance
enhancements of TanStack Table.

Built for modern React and with a foundation of signals, the Data Grid is designed to
provide a seamless and efficient experience for developers and users alike. With its
powerful features and intuitive API, the Data Grid is the perfect solution for any
data-heavy application.

> **Note:** The Data Grid is a client component.

## Installation


```bash
npm install @cerberus/data-grid@npm:@cerberus-design/data-grid
```


### Dependency Requirements

The `DataGrid` component requires the following dependencies to be installed in
your local project:

- [`react`](https://react.dev/)
- [`react-dom`](https://react.dev/)
- [`@pandacss/dev`](https://panda-css.com/docs/overview/getting-started)
- [`@cerberus/panda-preset`](https://cerberus.digitalu.design/docs/get-started/installation)

> **Note:** The Data Grid utilizes the Cerberus ecosystem to ensure styling, APIs, and customization are consistent.

## PandaCSS Setup

Once you have installed the Data Grid, update the `include` array in your `panda.config.ts` file:

<CodeSnippet
  snippet={`export default createCerberusConfig({
    include: [
      "./node_modules/@cerberus/data-grid/dist/panda.buildinfo.json",
      // ...your other stuff,
    ],
})`}
/>

## React

The Data Grid uses the Cerberus React library internally to ensure consistency.
However, if your project **does not use the Cerberus React library**, you will need
to export the Data Grid differently:


```tsx

```

<br />

This will provide a Data Grid wrapped in the [Cerberus Context Provider](/docs/components/cerberus-context)
which provides the necessary context for the Data Grid to function correctly.

## Typescript

The Data Grid is built with TypeScript and provides type definitions for all props and
methods. This ensures that your code is type-safe and helps catch errors early.

## Server-side Rendering

The Data Grid is built for modern React and is designed to work seamlessly with server-side
rendering frameworks like Next.js. Each example will display `use client` directives
when client-side rendering is required.


---
## pagination

---
title: Pagination
description: Learn how to use pagination in the data grid.
package: 'data-grid'
---





## Overview

Pagination allows you to display a subset of data at a time which can be navigated
through using the pagination controls.

**By default, the pagination is handled on the client**. This means you have to give
the rows of all pages to the Data Grid. If your dataset is too big, and you want
to fetch the pages on demand, you can create a custom action in a custom
[Toolbar](/docs/data-grid/toolbar) action.

## Implementing Pagination

You must opt-in to pagination by setting the `initialState.pagination` prop to either `true`
or using a `PaginationOptions` object on the Data Grid. Doing so will display a
static footer of pagination controls at the bottom of the grid.


```tsx


export function BasicDemo() {
  return <Pagination count={5000} pageSize={10} siblingCount={2} />
}
```


## Page Sizes

> **Note:** The Data Grid comes built-int with a range of three predefined page sizes: 25, 50, and 100.

To enable custom page sizes, you need to provide a `customRange` value to the
`pagination` options. This should be an Array of numbers representing the page sizes to display in the dropdown.

When this is provided, the Data Grid will use the first value in `customRange` as the initial page size.


```tsx
Example not found
```


## Default Page

To set the default page, you can provide a `defaultPage` value to the `pagination` options.


```tsx
'use client'

import {
  createSelectCollection,
  Field,
  For,
  Group,
  Option,
  Pagination,
  Select,
  type SelectValueChangeDetails,
  Text,
  usePaginationContext,
} from '@cerberus-design/react'



export function PageDemo() {
  return (
    <VStack textAlign="center" w="3/4">
      <Pagination count={20} defaultPageSize={2}>
        <HStack justify="flex-end" pb="md" w="full">
          <PageSize />
        </HStack>

        <UserList />
      </Pagination>
    </VStack>
  )
}

function PageSize() {
  const pagination = usePaginationContext()
  const collection = createSelectCollection([
    { label: '2', value: '2' },
    { label: '4', value: '4' },
    { label: '6', value: '6' },
    { label: '8', value: '8' },
    { label: '10', value: '10' },
  ])

  return (
    <HStack justify="flex-end" w="full">
      <Text as="small" color="page.text.100" textStyle="label-sm">
        Items per page:
      </Text>

      <Field label="Select page size" hideLabel w="initial">
        <Select
          collection={collection}
          onValueChange={(details: SelectValueChangeDetails) =>
            pagination.setPageSize(Number(details.value))
          }
          value={[String(pagination.pageSize)]}
          w="fit-content"
        >
          <For each={collection.items}>
            {(item) => <Option key={item.value} item={item} />}
          </For>
        </Select>
      </Field>
    </HStack>
  )
}

function UserList() {
  const pagination = usePaginationContext()
  return (
    <Group orientation="vertical" pb="lg" w="full">
      {pagination.slice(users).map((user) => (
        <HStack
          key={user.id}
          bgColor="page.bg.100"
          gap="md"
          p="md"
          rounded="sm"
          w="full"
        >
          <Text color="page.text.initial" textStyle="body-md">
            {user.name}
          </Text>
          <Text as="small" color="page.text.100" textStyle="label-sm">
            {user.email}
          </Text>
        </HStack>
      ))}
    </Group>
  )
}
```


## Count

For **server-side pagination** where the total count is known beforehand, you can
provide a `count` value to the `pagination` options.

This also means that the Data Grid will no longer automatically calculate the
total number of pages based on the `count` and `pageSize` values
(as per usual for server-side pagination).


```tsx
Example not found
```


## Page Change Action

You can trigger a callback when the page change action is fired by providing a
`onPageChange` prop to the Data Grid. This will recieve a `details` object with
the current page number and page size.

This is useful for analytics or tracking page changes.

> **Note:** If you plan on fetching more data on page change, the grid state will reset which includes the page state. This is due to the nature of client-side pagination.


```tsx
Example not found
```


## Options

The `pagination` options accept the following properties:


```tsx
Example not found
```


| Params        | Required | Description                                                                                                        |
| ------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `defaultPage` | `false`  | The index of the page to display by default.                                                                       |
| `count`       | `false`  | The total number of items in the grid. **This is useful for server-side pagination design**                        |
| `pageSize`    | `false`  | The initial page size to use when the grid is first rendered. **This must be one of the values in `customRange`.** |
| `customRange` | `false`  | An array of custom page sizes to display in the dropdown. **This must include the `pageSize` value.**              |


---
## pinning

---
title: Column Pinning
description: Learn about the column pinning feature in the Data Grid component.
package: 'data-grid'
---





## Overview

Pinned columns (also known as sticky, frozen, and locked) are visible at all times 
while scrolling the Data Grid horizontally. Users can access this feature through 
the column menu to pin and unpin columns to either the left or right side. 

## Implementing column pinning

You must opt-in to column pinning by setting the `features.pinning` prop to `true` or 
utilzing the options object. Doing so will display the pinning options in the column menu.


```tsx
Example not found
```


## Default Pinning

To set a column to be pinned by default, you can use the `defaultPosition` property 
in the `features.pinning` object.


```tsx
Example not found
```


## Options

The `pinning` feature accepts either a `boolean` or an object with the following properties:


```tsx
Example not found
```


| Params    | Required    | Description                                        |
| --------- | ----------- | -------------------------------------------------- |
| `defaultPosition` |  `false` | Whether the column should be pinned by default. |


---
## quickstart

---
title: Data Grid Quickstart
description: Learn how to use the Data Grid component in your React application.
package: 'data-grid'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage


```tsx
Example not found
```


## Understanding the Data Grid

The Data Grid is a complex component that provides a wide range of features for 
displaying and interacting with data. It includes a variety of helpers to create
an enhanced developer experience.

## Step 1: The Data

The DataGrid accepts any form of data structures. Data is not what drives the 
component - **defined columns** are. All that matters for your data is that it 
is typed.


```tsx
Example not found
```


## Step 2: Setup Columns

**Columns are the engine that run the Data Grid.**

Columns are defined using the `createColumnHelper`. This will provide a strictly
typed interface for defining individual columns.

Pass in your data type to the `createColumnHelper` function and build your columns.


```tsx
Example not found
```



### Creating Columns

Once you have setup your helper singleton, you can start building columns. 

There are three methods available to create columns: 

- `display`: Non-interactive columns.
- `accessor`: Interactive columns that utilize the `features` options.
- `accessorFn`: Interactive columns that allow your to define custom logic for rendering cells.


```tsx
Example not found
```


<br />

You can learn more about the columns in on the [Columns](/docs/data-grid/columns) page.

### Use the DataGrid

The final step is to add the DataGrid component to your application. You simply
pass in the data, columns, and any other feature-related props.

> **Note:** For contstrained layouts (seen in the demo preview), we recommend wrapping the DataGrid in a container that has a strict height defined.


```tsx
Example not found
```


<br />

The next pages cover each feature in detail.


---
## sizing

---
title: Data Grid Sizing
description: Learn about sizing the rows in the Data Grid component.
package: 'data-grid'
---





## Overview

Row sizing options are avaiable for the Data Grid component vai the `rowSize` prop.
Utilizing this will either reduce or increase the visual size of all rows 
(including headers).

This is a great option if you want to display more content within a cell without
it feeling compact.

## Size Options

The Data Grid has a flexible sizing system that allows you to choose from predefined
size options or define a custom size if needed. **All sizes are defined in pixels**
to ensure virtualization works correctly.

When no `rowSize` is provided, the Data Grid will use the `sm` size.

> **Note:** Cells are rendered in a flex row container, to enable the use of any flex-related property for your content.

### Predefined Sizes

There are several predefined size options available: `xs` to `xl`.


```tsx
Example not found
```


#### Predefined Size Guide

| Size | Pixel Value |
|------|-------------|
| `xs` | 32          |
| `sm` | 40          |
| `md` | 48          |
| `lg` | 56          |
| `xl` | 64          |

### Custom Sizes

You can also define a custom size by passing a number directly to the `rowSize` prop.
This allows you to use any pixel value you need.


```tsx
Example not found
```


---
## slots

---
title: Slots
description: Learn about the layout slots of the Data Grid component.
package: 'data-grid'
---





## Overview

The Data Grid comes with placeholder content slots that live within the contextual provider.
When provided, any component used for the slot will have access to the Data Grid context
via the `useDataGridContext` hook.

You can utilize a slot by adding the name of the slot as a property to the `DataGrid` component
and passing in the preferred `ReactNode`.

**Data Grid Slots**

- **Toolbar**: placed above the grid. Commonly used for global actions.
- **Footer**: placed below the grid.

> **Note:** Remember that all slot positions are constrained to the dimensions provided by the parent component wrapping your Data Grid.

## Slot Preview

In this demo we show the location of each slot provided for the Data Grid.


```tsx
Example not found
```


---
## sort

---
title: Column Sorting
description: Learn about the column sorting feature in the Data Grid component.
package: 'data-grid'
---





## Overview

Sorting allows users to list the data in ascending or descending order. There are
three ways for a user to sort:

1. **Clicking on the header-cell icon**: This will toggle the order from ascending to descending and vice versa.
2. **Using the sort menu**: Users can also use the sort menu to strictly determine the order of the data.
3. **Multi-column sorting**: Hold the `Shift` key while clicking on the second sort button.


```tsx
Example not found
```


## Implementing column sorting

You must opt-in to column sorting by setting the `features.sort` prop to `true` or 
utilzing the options object. Doing so will display the sorting options in the column menu.


```tsx
Example not found
```


## Multi-column Sorting

Multi-column sorting is enabled by default on the toggle sort button. To use 
multi-column sorting hold the `Shift` key while clicking on the second sort button.


```tsx
Example not found
```


## Custom Comparator

A comparator determines how two cell values should be sorted. The default comparator 
uses the vanilla JavaScript basic comparison of `a` and `b`. 

When using the `accessorFn` method, the comparator uses the value returned from the 
`accessorFn` callback provided as the first argument.

To provide a custom comparator, you can pass a function as the `features.sort.comparator` option.

> **Note:** Dates will naturally sort in order without any customization. This example just shows how to customize the sorting behavior.


```tsx
Example not found
```


## Options

The `sort` feature accepts either a `boolean` or an object with the following properties:


```tsx
Example not found
```


| Params    | Required    | Description                                        |
| --------- | ----------- | -------------------------------------------------- |
| `firstSortDirection` | `false` | The initial sort direction for the column. |
| `comparator` | `false` | A custom comparator function for sorting. |


---
## theme

---
title: Data Grid Theme
description: Learn how to customize the theme for the Data Grid component.
package: 'data-grid'
---






## Overview

A its core, the Data Grid controls little to nothing regarding how it _looks_.

Essentially, the visual style is controlled by the **cell content**, Cerberus React
primitives it uses (e.g., menus, pagination, etc.), and the Cerberus theme
that is active from your Panda CSS config.

Having said that, what little things are visually styled, can be customized via
the `theme` prop of the `DataGrid` component.

## Usage

To customize the theme, pass an Object of options to the `theme` prop in the `DataGrid`
component.

In the example below, we change six properties in addition to creating a vertical
legend to show to the left of the Data Grid.

Take note of how the Column definitions are also providing customized cell content
in a way that also changes the appearance of the layout.


```tsx
Example not found
```


## Type Safety

To provide the best typescript experience, we recommend assigning the `ThemeOptions`
type to a constant that will define your theme. This will enforce auto-completion
while holding the constant accountable to fulfill the `ThemeOptions` type.


```tsx
Example not found
```


## Theme Options

The `theme` prop takes an Object with the following properties:

| Params                      | Type     | Description                                                                            |
| --------------------------- | -------- | -------------------------------------------------------------------------------------- |
| `borderColor`               | `string` | The external border of the Data Grid container. The default is `page.border.initial`   |
| `border`                    | `string` | The border width and style of the Data Grid component. Default is `1px solid`.         |
| `rounded`                   | `string` | The border radius of the Data Grid component. Default is `lg`.                         |
| `rowBgColor`                | `string` | The background color of the row. Default is `page.surface.100`.                        |
| `rowHoverBgColor`           | `string` | The background color of the row on hover. Default is `page.surface.200`.               |
| `rowEvenBgColor`            | `string` | The background color of the even rows. Default is `page.surface.initial`.              |
| `headCellBgColor`           | `string` | The background color of the head cell. Default is `page.bg.initial`.                   |
| `headCellBorderBottomColor` | `string` | The border color for the bottom border of the head cell. Default is `page.border.200`. |
| `gridCellBorderColor`       | `string` | The border color of the grid cell. Default is `page.border.200`.                       |
| `gridCellPinnedBorderColor` | `string` | The border color of the pinned grid cell. Default is `page.border.200`.                |

> **Note:** Manipulating any values outside of the ones provided in ThemeOptions could yield to the layout breaking and virtualization no longer working. Do so with extreme caution.


---
## toolbar

---
title: Toolbar
description: Learn how to create custom toolbars in the Data Grid component.
package: 'data-grid'
---





## Overview

The Toolbar is a reserved area above the Data Grid component typically used for
global actions for the grid itself.

To add a custom toolbar, you can use the `toolbar` prop and pass a React component.

Since the toolbar is positioned within the Data Grid component, **it shares the same
height restrictions as the grid itself**. Ensure your parent height is set appropriately
to accommodate the toolbar.

<NoteAdmonition description="If you don't need the context of the grid, we recommended rendering your toolbar outside of the Data Grid component." />


```tsx
Example not found
```


## Grid Context

To access the Data Grid context, you use the `useDataGridContext` hook which provides
a signal driven store for reading and updating state in a highly performant way.

Read the [Data Grid Context](/docs/data-grid/context) documentation for more details.


---
## visibility

---
title: Column Visibility
description: Learn about the column visibility feature in the Data Grid component.
package: 'data-grid'
---





## Overview

Column visibility allows you to control which columns are visible in the Data Grid.
Users can access this feature through the column menu to show/manage columns.

There will be two options presented to the user:

- **Hide**: Hides the column from view.
- **Manage**: Allows the user to manage the visibility of all columns.

Once a column is hidden, it will not be visible in the Data Grid and the only way to show it is through the **Manage** option.

When there is only a single visible column left in the Grid, only the _Manage_ option will be displayed.

### How it works

When the visibility feature is enabled and the Manage popover is displayed, the user will
see the list of all columns and can toggle their visibility via the checkbox next to each column.

If the column list equals or exceeds 7 columns, a Search input will be displayed to filter the column list.

## Implementing column visibility

You must opt-in to the column visibility feature by setting the `features.visibility` prop to `true` or by utilizing the options object. Doing so will display the visibility options in the column menu.


```tsx
Example not found
```


## Default Visibility

To set a column to be hidden by default, you can use the `defaultHidden` property
in the `features.visibility` object.


```tsx
Example not found
```


## Options

The `visibility` feature accepts either a `boolean` or an object with the following properties:


```tsx
Example not found
```


| Params          | Required | Description                                     |
| --------------- | -------- | ----------------------------------------------- |
| `defaultHidden` | `false`  | Whether the column should be hidden by default. |


---
## context-7

---
title: Context-7
description: Learn how to use Context-7 to your agentic advantage
---



## Cerberus Context

Cerberus has a Context7 MCP that you can use to your agentic advantage:

- [**Cerberus Repository MCP**](https://context7.com/omnifed/cerberus): The official Cerberus repository MCP on Context7.
- [**Cerberus Docs MCP**](https://context7.com/websites/cerberus_digitalu_design/llms.txt?tokens=10000): The official Cerberus docs website MCP on Context7.

This resource contains context, skills, chat, benchmark, and suggestions.

To learn more about how to utilize Context7, see their [official documentation](https://context7.com/docs/overview).

## What is Context 7?

Context7 brings up-to-date, version-specific documentation and code examples directly into your AI coding assistant. That means no more outdated code or hallucinated APIs.

**Without Context 7 :x:**

LLMs rely on outdated or generic information about the libraries you use:

- :x: Code examples based on old training data
- :x: Hallucinated APIs that don’t even exist
- :x: Generic answers for old package versions

**With Context 7 :white_check_mark:**

Context7 MCP pulls up-to-date, version-specific documentation and code examples straight from the source — and places them directly into your prompt.

Add `use context7` to your prompt in Cursor:


```tsx
Create a Next.js middleware that checks for a valid JWT in cookies and redirects unauthenticated users to `/login`. use context7
```


---
## contributing

---
title: Contributing to Cerberus
description: Learn how to contribute to the Cerberus Design System, including guidelines for code contributions, documentation, and more.
---

## How to Contribute

Cerberus is an open-source project, and we welcome contributions from the community. Whether you're a seasoned developer or just starting out, there are many ways you can help improve Cerberus.

1. **Report Issues**: If you find a bug or have a feature request, please open an issue on our [GitHub repository](https://github.com/omnifed/cerberus)
2. **Submit Pull Requests**: If you have a fix or a new feature, feel free to submit a pull request. Make sure to follow our [contribution guidelines](#contribution-guidelines).
3. **Documentation**: Help us improve our documentation by suggesting edits or adding new content.
4. **Spread the Word**: Share Cerberus with your friends and colleagues. The more people use it, the better it gets!

## Contribution Guidelines

You can find our contribution guidelines in the [CONTRIBUTING.md](https://github.com/omnifed/cerberus/blob/main/CONTRIBUTING.md) file in the root of the repository. Please read through it before submitting any contributions.

## Code of Conduct

We expect all contributors to adhere to our [Code of Conduct](https://github.com/omnifed/cerberus/blob/main/CODE_OF_CONDUCT.md) to ensure a welcoming and inclusive environment for everyone.


---
## faq

---
title: FAQ
description: Frequently Asked Questions about Cerberus Design System
---

### Why does the package path for react 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 have a specific `baseUrl` in our tsconfig.json?

In order for our React components to know where to find the styled-system APIs, it needs to know where to look. By setting the `baseUrl` to the root of your project, we can use the `styled-system` import path without needing to know the exact location of the file.


---
## get-started

---
title: Get Started
description: A step-by-step guide to get started with Cerberus
---






### What is Cerberus?

Cerberus is a Design System factory built on top of Panda CSS. This means you 
can create the strict ruleset of your own design system guidelines with the 
flexibility of a UI-library.

Cerberus provides an extensive ecosystem which consists of:

1. **PandaCSS Presets**: core tools and themes
2. **React**: flexible primitive components with accessibility features
3. **Data Grid**: a compositional component that is feature-rich and accesssible
4. **Signals**: a signal-based reactive state management system made for React

#### Panda Presets

Cerberus has multiple presets that can be used to customize the look and feel of 
your application. You can pick and choose which presets you want to use.

- **Panda Preset**: the core base (required) - a set of tokens, recipes, conditions, utilities, 
patterns. Comes with the _Cerberus Theme preset_ built in.
- **Theme Presets**: a set of customized semantic tokens and conditions that change the colors of the semantic theme palettes

> **Note:** The only preset required to get started with Cerberus is the Panda Preset. You do not need to add any additional themes when using the core preset.

## React

The React package is a set of primitive React components (low-level layers) that
consume the _core preset_ recipes for sytling. Anything in the [Components](/docs/components/overview)
section of the docs comes from the React package.

The React library comes with the following benefits:

- **[Factory](/docs/styling/cerberus-factory)**: a helper to create super-powered JSX elements
- **[Composition](/docs/components/composition)**: easily replace parent components with the child via `asChild` (built into the Factory)
- **[Primitives]**: low-level component layers to build your own version of a component
- **[Abstractions]**: streamlined abstractions for more complex components

### Using Icons

The React library provides a default set of icons ([Carbon Icons](https://carbondesignsystem.com/elements/icons/library/)) 
via the [Cerberus Context Provider](/docs/components/cerberus-context). However,
if you are interested in using a different icon set, you can simply register it
with the provider via the `defineIcons` helper.

## Data Grid

The Data Grid package is a single component that provides a powerful and flexible 
way to display tabular data. It uses the React library to create and manage the grid
in addition to the Signal library to manage the state.

We call advanced component APIs like this **compositional components**. 

## Signals

Signals are a way to manage reactive state that is external to the React library.
This concept has become popular thanks to [SolidJS](https://docs.solidjs.com/).
Thus, we have created a wrapper around the [Preact Signals Core](https://preactjs.com/guide/v10/signals/)
library to allow signal usage in React components.

This is a powerful way to ensure React components are optimized for performance and
only re-render when absolutely necessary. **This ultimately means that your application
will show state updates without any unnecessary re-renders.**.

The Signals library powers the Data Grid package.

## Doc Sections

The docs are organized into sections that cover different aspects of Cerberus:

- **[Get Started](/docs/get-started)**: General overview and installation instructions.
- **[Components](/docs/components)**: Everything related to the React package.
- **[Data Grid](/docs/data-grid)**: Everything related to the Data Grid package.
- **[Styling](/docs/styling)**: Everything related to using styles in Cerberus.
- **[Theming](/docs/theming)**: Everything related to theming and theme customization in Cerberus.


---
## installation

---
title: Installation
description: A step-by-step guide to install Cerberus
---








## Setup Guide

For a better developer experience, we recommend using either [Deno](https://deno.com/)
or [pnPm](https://pnpm.io/) as your package manager which has first class support for [JSR](https://jsr.io/) 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](https://panda-css.com/docs/installation/nextjs) 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](https://jsr.io/docs/using-packages) as possible
to ensure a better experience for developers.


```bash
npx jsr add @cerberus/panda-preset
```


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


```tsx
// Source available in static configuration: {DEMOS.panda}
```


<br />

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:


```tsx
// Source available in static configuration: {DEMOS.fonts}
```


### 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.


```tsx
// Source available in static configuration: {DEMOS.layout}
```

<br />

**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.


```tsx
// Source available in static configuration: {DEMOS.config}
```


<NoteAdmonition
  description={
    <>
      If using Deno, simply setup your import map to include the <code>styled-system/\*</code>{' '}
      alias.
    </>
  }
/>

### Step 2 - Install Cerberus React

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


```bash
npm install @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.


```tsx
// Source available in static configuration: {DEMOS.reactPanda}
```


### 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.


```tsx
Example not found
```

<br />

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

### Optional - Registering Custom Icons

React comes built in with the [Carbon Icons](https://carbondesignsystem.com/elements/icons/library/) 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](/docs/components/cerberus-context)

### Optional - Multi-theme support

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


```tsx
// Source available in static configuration: {DEMOS.multiTheme}
```


### 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:


```tsx
// Source available in static configuration: {DEMOS.tips}
```

<br />

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


```bash
npm run up:cerberus
```


---
## llms

---
title: LLMS.txt
description: Learn how to get tools like Cursor, Windsurf, GitHub Copilot, ChatGPT, and Claude to understand Cerberus.
---

## What is LLMs.txt?

We support [LLMs.txt](https://llmstxt.org/) files for making the Cerberus UI documentation available to large language models.

This feature helps AI tools better understand our ecosystem, its APIs, and usage patterns.

## Available Routes

We provide multiple routes to help agents access our documentation:

- [**/llms.txt**](/llms.txt) - Contains a structured overview of all documentation pages. This is a table of contents for the agent documentation.
- [**/llms-full.txt**](/llms-full.txt) - Contains the full documentation content for all pages.

---

Page specific docs are available if you have a limited context window.

These routes follow the current naming convention: `llms/[section]/[slug].txt`

For example, here are some pages from the different sections of the documentation:

- [**/llms/components/button.txt**](/llms/components/button.txt) - Button component documentation
- [**/llms/data-grid/overview.txt**](/llms/data-grid/overview.txt) - Data grid overview documentation
- [**/llms/signals/overview.txt**](/llms/signals/overview.txt) - Signals overview documentation
- [**/llms/styling/cerberus-factory.txt**](/llms/styling/cerberus-factory.txt) - Styling Cerberus Factory
- [**/llms/theming/overview.txt**](/llms/theming/overview.txt) - Theming overview documentation

## Usage with AI Tools

### Cursor

Use the `@Docs` feature in Cursor to include the LLMs.txt files in your project. This helps Cursor provide more accurate
code suggestions and documentation for Cerberus components.

[Read more about @Docs in Cursor](https://docs.cursor.com/context/@-symbols/@-docs)

### Windsurf

Reference the LLMs.txt files using `@` or in your `.windsurfrules` files to enhance Windsurf's understanding of Cerberus
components.

[Read more about Windsurf Memories](https://docs.codeium.com/windsurf/memories#memories-and-rules)

### Copilot

Use the LLMs.txt files in GitHub Copilot to improve code suggestions and documentation for Cerberus components.

[Read more about GitHub Copilot](https://docs.github.com/en/copilot)

### Other AI Tools

Any AI tool that supports LLMs.txt can use these routes to better understand Cerberus. Simply point your tool to any of
the routes above.


---
## themes

---
title: Theme Presets
description: Learn how to use different themes in Cerberus
---




> **Note:** Every theme listed is featured on this website in the theme selector menu located in the top right corner.

Cerberus has a set of additional theme presets that you can use to quickly apply a consistent look and feel to your application.

You can either use the official theme presets or create your own theme and submit it as a pull request to the [Cerberus GitHub repository](https://github.com/omnifed/cerberus).

## List of Cerberus Themes

- [`@cerberus/preset-cerberus-theme`](https://github.com/omnifed/cerberus/tree/main/packages/preset-cerberus-theme): the base theme which comes built-in with Cerberus
- [`@cerberus/preset-acheron-theme`](https://github.com/omnifed/cerberus/tree/main/packages/preset-acheron-theme): A earthy toned theme
- [`@cerberus/preset-elysium-theme`](https://github.com/omnifed/cerberus/tree/main/packages/preset-elysium-theme): A high-contrast theme
- [`@cerberus/preset-oceanus-theme`](https://github.com/omnifed/cerberus/tree/main/packages/preset-oceanus-theme): A blue theme

### Contents

A theme preset should contains the following configuration updates and helpers:

- [Semantic Tokens](/docs/theming/colors#semantic-tokens)
- Theme-specific condition using the naming convention `[themeName]Theme`
- A `getThemeName` helper function

### Package Naming

Theme packages should be named `@cerberus/preset-[themeName]-theme`.

## Using Official Theme Presets

To use any of the official theme presets, install the package and update your `panda.config.ts` file accordingly.

<CodeSnippet snippet={`// panda.config.ts


import {
  acheronTheme,
  getAcheronThemeName,
} from '@cerberus/preset-acheron-theme'

export default defineConfig({
    ...cerberusConfig,
  
    include: ['./src/**/*.{ts,tsx,js,jsx}'],
    exclude: [],
    
    presets: [cerberusPreset(), acheronTheme],
    
    staticCss: {
      themes: ['cerberus', getAcheronThemeName()],
    },
})`} />


---
## batch

---
title: Batch Updates
description: Learn how to update multiple signals at once in React.
package: 'signals'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The `batch` primitive is useful when you want to make multiple signal updates at
once. This can include individual updates or signals updating simultaneously to
a peer signal updating.

In this example, our batch block updates two signals at once which reference the
same signal value.


```tsx
Example not found
```


## API

`batch` accepts a callback containing multiple signal `Setters` and doesn't return
any value.


---
## create-computed

---
title: Computing Signal Values
description: Learn how to combine signals to create a single value in React.
package: 'signals'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

Sometimes you may want to create a new signal that is computed from other signal
values. This is where the `createComputed` primitive comes in.

This API is similar to the native `useMemo` hook from React without the need for
providing a depedency Array.

In this example, we create a computed signal based on two raw signals. Likewise,
we utilize the `createEffect` primitive which sets the signal value without React
getting involved.

> **Note:** In order for createComputed to track signal subscriptions, it is required that Accessors are used in the body.


```tsx
Example not found
```


## API

`createComputed` accepts a callback function and returns the value in a form of
a Signal `Accessor`.

**Important:** be sure to use `Accessor` getters _not_ values within a `createComputed`
primitive. Ignoring to do so will cause stale values that will not be updated.


---
## create-effect

---
title: Creating Effects
description: Learn how to create effects using Signals in React.
package: 'signals'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

When you want to do something in response to a signal changing, you can use the
`creeateEffect` primitive.

Effects come with the following benefits:

1. Can be used anywhere in your application (e.g., not constrained to components)
2. Can be nested within other effects
3. Can be used within native React effects
4. Auto-tracks signals (e.g., no dependency Array needed)

Basically, as long as the scope has access to a signal Accessor the usage is valid.

In this example, we utilize the `createEffect` to set the `isEven` signal value
when `getCount` is updated.

> **Note:** In order for createEffect to track signal subscriptions, it is required that Accessors are used in the body.


```tsx
Example not found
```


## With React effects

You can nest `createEffect` within the native React effect when you need to access
_the React component render lifecycle_.

<NoteAdmonition
  description={
    <>
      The createEffect primitive removes the overall need for native React effects.
      <br />
      <br />
      The only time you should use native React effects is if you need to access the{' '}
      <em>React component lifecycle</em>. All other scenarios can be achieved using any of the
      primitive APIs this library offers.
    </>
  }
/>


```tsx
Example not found
```


## API

`createEffect` accepts a callback Function and returns a Function. When the
return Function is called, it will unsubscribe the effect from the signal Observer.

**Important:** be sure to use `Accessor` getters _not_ values within a `createEffect`
primitive. Ignoring to do so will cause stale values that will not be updated.


---
## create-mutation

---
title: Creating Mutations
description: Learn how to update queries in React.
package: 'signals'
---







```tsx
// Source available in static configuration: {DEMOS.mutationMeta}
```


## Usage

`createMutation` allows you create a Mutation Factory that works alongside Cerberus Queries. Mutations provide _optimistic updates_ and invalidation options to keep your UI seamlessly "real-time" by fetching in the background on your behalf.

**Mutations are used when you want to make updates to data that is associated with a query.**

Likewise, if you have a query that will never have update-related actions associated with it - you don't need mutations.

## Creating Mutations

Creating a mutation requires two things:

1. A Promise to call when activated
2. Mutation options to utilize when `mutate` is called

Ultimately, when you create a mutation you are really just creating a factory that can be called where ever and whenever you are ready.


```tsx
Example not found
```


## Using Mutations

Depending on your goals will determine how to you the mutation. The following sections outline the different use cases whether you are optimistically updating or not.

**Mutations can live at any level**. All that matters is that the factory has access to the `query.key` to reference.

There are no restrictions to Cerberus Signal Primitives which means you can use them at any scope.

### Pattern 1: Optimistic Updates

Optimistic updates allow you to update the state of your query data which which will render in the UI immediately while calling the Promise-based mutation in the background.

This is done by using the `setQueryData` helper function.

**Utilizing this helper will allow your application to appearingly have "real-time" functionality.**

Once the mutation is settled, the return value will automagically overwrite the optimistic value. If these are the same - there will be no visual difference in the UI. If there is a descrepency, the UI will automagically be corrected.

To use optimitic updates, add the `onMutate` method to the options Object of your second argument and call the `setQueryData` helper to update the state.


```tsx
// Source available in static configuration: {DEMOS.optimisticMeta}
```

<br />

The `setQueryData` helper accepts a `query.key` with the same arguments that the original query expects. This is done by using the [`key` property](/docs/signals/create-query#api) from the original query.


```tsx
Example not found
```


### Pattern 2: Non-optimistically

If you are interested in a legacy approach that matches traditional application updates via visual loading states - simply omit the `onMutate` option (and thus not using `setQueryData`).

`onMutate` does not create the optimistic update - `setQueryData` does. So, if you needed the `onMutate` lifecycle method you can still use it.


```tsx
Example not found
```


### Within Components

To use mutations within a component, pass the factory to the `useMutation` hook. This will return an Object that contains the `mutate` method and any of the other [return properties](#return).


```tsx
// Source available in static configuration: {DEMOS.mutationUsageMeta}
```


## The Mutation Lifecycle

When you trigger a mutation that includes `onMutate` and `invalidate` handlers, Cerberus orchestrates a complex, highly-optimized sequence of events under the hood.

Understanding this lifecycle is key to mastering Optimistic UI. Here is the exact chronology of what happens the millisecond you call `mutate()`:

### 1. The Trigger

The user clicks a button and your component calls `mutate(payload)`.

### 2. The Optimistic Update (`onMutate`)

Before the network request even begins, Cerberus synchronously executes your `onMutate` callback.

- You use `setQueryData` to inject the expected result directly into the cache.
- **The Engine Lock:** Cerberus instantly increments an internal `version` integer on that specific cache node.
- **The UI Update:** The UI instantly snaps to the new state. Because this uses direct signal memory pointers, it executes in ~130 nanoseconds with zero main-thread blocking.

### 3. The Network Request

The asynchronous mutation function you defined in the factory (e.g., `api.updateUser`) is fired to the server. Your component can track this loading state using the isolated `pending` status.

### 4. Background SWR (`invalidate`)

Once the server responds successfully, your `invalidate` callback fires.

- It flags the target query cache as "stale."
- Because the UI already has data (your optimistic update), Cerberus **intentionally bypasses React Suspense boundaries**.
- A background Stale-While-Revalidate (SWR) fetch is quietly triggered to verify the data against the database. The user experiences absolutely zero UI flickering.

### 5. Resolution & The Version Lock

When the background SWR fetch finally resolves, the engine performs one final, critical check before saving the data: **The Version Lock.**

- It compares the cache's current version to the version it was when the fetch started.
- **If they match:** The background data perfectly overwrites the cache, confirming the database is in sync with the UI.
- **If they differ:** This means the user rapidly clicked `mutate()` again _while_ the background fetch was running. Cerberus realizes this fetch is now stale, intercepts the data, and silently aborts the update. This guarantees your users will never experience a "Flash of Unstyled Content" (FOUC) or see their UI snap backward during rapid interactions.

### Timeline Visualization

| Time   | Action                    | UI State         | Background Engine             |
| ------ | ------------------------- | ---------------- | ----------------------------- |
| 0ms    | User calls mutate()       | Instantly new    | version: 1, Cache updated     |
| 5ms    | Network request starts    | Instantly new    | Mutation pending              |
| 800ms  | Network request succeeds  | Instantly new    | invalidation triggers SWR     |
| 805ms  | Background query starts   | Instantly new    | fetching database state...    |
| 1800ms | Background query finishes | Stays consistent | Version check -> Cache synced |

## API

`createMutation` accepts the following options:

| Params  | Required | Description                                                  |
| ------- | -------- | ------------------------------------------------------------ |
| mutator | `true`   | The Promise-based function used when the `mutate` is called. |
| options | `false`  | An Object of conditional options for defined mutations.      |

### Mutation Options

The options Objecct contains the following optional properties:

| Property     | Type                                             | Description                                                          |
| ------------ | ------------------------------------------------ | -------------------------------------------------------------------- |
| `onMutate`   | `(variables: V) => void`                         | A callback to run when the mutation is triggered.                    |
| `onSuccess`  | `(data: T, variables: V) => void`                | A callback to run when the mutation is successful.                   |
| `onError`    | `(error: unknown, variables: V) => void`         | A callback to run when the mutation has errored.                     |
| `invalidate` | `'all' \| ((data: T, variables: V) => string[])` | A list of `query.key` to invalidate once the mutation has completed. |

### Return

`useMutation` returns a `MutationReturn` Object that contains the following properties:

| Index    | Type                                          | Description                                  |
| -------- | --------------------------------------------- | -------------------------------------------- |
| `mutate` | `(variables: V) => Promise<T>`                | A function used to trigger the mutation.     |
| `status` | `'idle' \| 'pending' \| 'success' \| 'error'` | The Promise-based status of the mutation.    |
| `error`  | `unknown \| undefined`                        | The error thrown when something bad happens. |
| `data`   | `T  \| undefined`                             | The data returned from the mutation.         |

### `setQueryData`

`setQueryData` doesn't return anything and accepts following properties:

| Index     | Type                          | Description                                                                                                                             |
| --------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `hashKey` | `string`                      | A unique key provide from calling the `query.key` method with the expected arguments passed in provided from the `onMutate` parameters. |
| `updater` | `(prev: T \| undefined) => T` | A setter function that returns the query data state if existing and expects the new state returned.                                     |


---
## create-query

---
title: Creating Queries
description: Learn how to create cached queries in React.
package: 'signals'
---







```tsx
// Source available in static configuration: {DEMOS.queryMeta}
```


## Usage

`createQuery` allows you define a fetcher factory that is **auto-fetched** and **cached** with or without an Accessor value. This creates a streamlined and high-performant
way to fetch data within your application with less effort.

The value of a query is inteded to be consumed by `useQuery`.

A query is just a fancy wrapper that subscribes to the signals Observer. This means
that **it can be used for any scenario that is Promise-based** - not just data-fetching. If you have a Promise, it can be a query.

See the [features table](#features-table) to understand how to best utilize queries
for each scenario you may have.

> **Note:** Queries are compatible with React Suspense and Error Boundaries.

## Creating Queries

Creating a query requires two things:

1. A Promise to call when activated
2. A unique key which is used to cache the result

Ultimately, when you create a query you are really just creating a factory that can be called where ever and whenever you are ready.


```tsx
Example not found
```


## Using Queries

Depending on your goals will determine how to use the query. The following sections outline the different use cases depending on whether you are fetching data within a component or outside of one.

There are no restrictions to Cerberus Signal Primitives which means you can use them at any scope.

### With Components

`createQuery` only _defines_ a query factory and does not actually call it. To use the
query in a component you must pass the returned value into the `useQuery` hook which re-runs when the arguments provided change.


```tsx
// Source available in static configuration: {DEMOS.queryUsageMeta}
```

<br />

The value returned is the result from calling the signal-tracked Accessor. This
is equivalent to the return value from the `useRead` hook.

### Without Components

There are two different patterns you can use depending on your fetching goals outside of components.

#### Pattern 1: Imperative Await (Standard Async)

If you just want to trigger the fetch and wait for the result in a standard async function, you can simply await the `Promise` attached to the pending state.


```tsx
Example not found
```


#### Pattern 2: Reactive Subscription (The Signal Way)

If you want a vanilla JS function to automatically react to the data whenever it arrives (or whenever it is invalidated and refetched in the background), you drop it into a `createEffect`.

This is incredibly useful for syncing data to vanilla DOM elements, Web Components, or external non-React stores.


```tsx
Example not found
```


## Streaming Reponses (Async Generators)

Cerberus queries also support streaming data via [Async Generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator). This is powerful if you are using an LLM API or your local API supports data streaming.


```tsx
Example not found
```


## Server Component Pattern

In an SSR environment, you execute the factory's **raw fetcher directly**, bypassing the reactive cache. Then, you pass that data down to your Client Components to "hydrate" or seed the Cerberus cache, ensuring the client doesn't double-fetch on mount.

This is the standard SSR pattern for React.

### 1. Server Component (Fetching)

Expose the raw, stateless fetcher function from your factory. You simply await it like a standard asynchronous function.


```tsx
Example not found
```


### 2. Client Component

On the client side, use the `initialData` property. If the Cerberus cache is empty, it will instantly seed the cache with the server's data, skipping the `<Suspense>` boundary entirely.


```tsx
Example not found
```


## Optimistic Updates

Queries have a built-in optimistic store when combined with [Mutations](/docs/signals/create-mutation). This means the UI will update in "real-time" while the query will fetch in the background and eventually overwrite the optimistic store.

Mutations are only necessary if you are _writing updates_. If your query is only intended to be read-only, it will automagically fetch when the params change.

## Features Table

| Feature            | With Signal        | Without Signal     |
| ------------------ | ------------------ | ------------------ |
| auto-intial fetch  | :white_check_mark: | :white_check_mark: |
| auto-refresh fetch | :white_check_mark: | :white_check_mark: |
| caching            | :white_check_mark: | :white_check_mark: |
| requires mutation  | :x:                | :x:                |

## API

`createQuery` accepts the following options:

| Params         | Required | Description                            |
| -------------- | -------- | -------------------------------------- |
| `Promise<any>` | `true`   | The Promise to call when activated.    |
| `key`          | `true`   | A unique key used for caching queries. |

### Return

`createQuery` returns the value of the Promise along with some additional properties:

| Property      | Type   | Description                                                     |
| ------------- | ------ | --------------------------------------------------------------- |
| `key`         | `UUID` | A uniqe ID to be referenced in the mutation `invalidate` Array. |
| `currentArgs` | `Args` | The args passed into `createQuery` stored in a reference.       |

> **Note:** The query.key is SHA generated from the contents of the query parameters. This means, if you have multiple signal-like queries, they should each have unique return values or else they will be synced together.

### Typing

`createQuery` accepts two arguements to strictly type the return result `<CacheNode, Args>`. These are naturally deferred through our strict type chain. This means you don't need to worry about it outside of rare use cases.

However, we do recommend using this if you are creating a query that doesn't expect any arguments: `createQuery<string, void>(...)`.


---
## create-signal

---
title: Creating Signals
description: Learn how to create fine-grained signals in React.
package: 'signals'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

When you want to create a signal **outside of a component** context. This can be
used globally, in a store, or any other way your purpose needs.

There are two ways to read a global signal within a component JSX:

1. `ReactiveText` (recommended) for fine-grained reactivity
2. `useRead` hook for reference consumption within JSX

## Basic State

`createSignal` allows you to manage state outside of the React render context.


```tsx
Example not found
```


## Reading State

The easiest way to get the current value of primitive-based signal is the `ReactiveText` component (which provides fine-grained reactivity).

When you need to reference a signal in any JSX-related context (e.g., `Show` or `For`) use the `useRead` hook to obtain the value.


```tsx
Example not found
```


> **Note:** We always recommend utilizing ReactiveText over useRead to provide better control over React rendering in addition to a cleaner DX.

## Setting State

With Cerberus Signals, how you set the state no longer matters. You are free to
use mutation or immutability. Both results will yield the same high performant and
reliable reactivity.

In this example we utilize the `createComputed` primitive to create a reactive
signal which provides a computational value. This is similar to the native React
`useMemo` hook.


```tsx
Example not found
```


<NoteAdmonition description="Notice how the createComputed primitive doesn't require a dependency Array? In Cerberus Signals, we auto-detect signals so you don't have to waste time declaring." />

### Objects and Arrays

When storing Objects or Arrays (any non-Primitiva value) in a signal, we recommend **using immutable updates** when setting new values. Doing so will ensure the best performance outcome since the graph uses strict equality (`!==`) to detect changes.


```tsx
Example not found
```


## Stores

You can create global stores to read and manage state across your entire application,
or simply devote to a single feature (this is how the [Data Grid](/docs/data-grid/overview)
is designed).

This allows you to have an "multi-signal" and action based solution that will
both improve React rendering performance and code scalability.


```tsx
Example not found
```


## API

`createSignal` accepts the following options:

| Params         | Required | Description                                |
| -------------- | -------- | ------------------------------------------ |
| `initialValue` | `false`  | The initial value to set for the accessor. |

### Return

`createSignal` returns a `SignalTuple<T>` Array of the following values:

| Index | Type          | Description                                           |
| ----- | ------------- | ----------------------------------------------------- |
| 0     | `Accessor<T>` | A function that returns the latest value when called. |
| 1     | `Setter<T>`   | A function to update the signal value.                |


---
## create-store-context

---
title: Contextual Signal Stores
description: Learn how to create Context-based signal stores in React.
package: 'signals'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Introduction

With Cerberus Signals, you can create global (signal-based) stores that manage
data and actions in a single place. Sometimes, you may want this scoped to an
application or component instance.

For this use case, we have the `createStoreContext` primitive.

This primitive will create both a Provider and getter hook heavily typed to the
store data passed in.


```tsx
Example not found
```

<br />
In this demo we have a global store that manages signals. We then generate the context
APIs and pass the `MyStore` type so we obtain strict type accountability.

In our main component we use the `StoreProvider` and pass our store to the
`createStore` prop.

In the child component we utilize the `useStore` hook to gain access to the store.

> **Note:** Remember that anytime you want to read a signal from a primitive - you need to either use ReactiveText or useRead to subscribe to the signal.

## API

`createStoreContext` doesn't accepts the following props:

| Property | Type     | Description                                                            |
| -------- | -------- | ---------------------------------------------------------------------- |
| `name`   | `string` | Optional. The name of the store to assign as the context display name. |

### Return

`createStoreContext` returns an Object with two properties:

| Property        | Type          | Description                               |
| --------------- | ------------- | ----------------------------------------- |
| `StoreProvider` | `ElementType` | The React Context Provider for the store. |
| `useStore`      | `() => T`     | A function to get the store context.      |


---
## data-fetching

---
title: Signals Data Fetching
description: Learn the fundamentals of fetching data using Signals.
package: 'signals'
---






## Introduction

Fetching data from a remote API or database is a core task for most applications.
Cerberus Signals provide foundational primitives like [`createQuery`](/docs/signals/create-query)
and [`createMutation`](/docs/signals/create-mutation) to manage asynchronous data.

Cerberus Signals data fetching APIs come with the following benefits:

1. **High performing**: our benchmarks outperform Tanstack queries by over 60% in some areas
2. **Caching**: all queries are cached until invalidated
3. **Optimistic updates**: built in support for "real-time" optimistic UI updates
4. **Data Streaming**: compatible with Async Generators for LLM responses
5. **SSR Sync**: fetch data on the server and sync it to a client-side query
6. **Suspense**: native support for React Suspense
7. **Error Boundaries**: native support for Error Boundaries

## Fetching Data

To fetch (and cache) data using signals, simply follow two steps:

1. Define a query factory via [`createQuery`](/docs/signals/create-query)
2. Use the factory via [`useQuery`](/docs/signals/use-query) in your component

In this example we use a **Signal to trigger a new query request**. When using this design you, _opt-out_ of optimistic UI updates and fallback to legacy loading-based UI changes.


```tsx
Example not found
```

<br />

In this example there are a few things happening:

1. The "backend API"
2. The query factory
3. The component using the query
4. An action that updates the global `currentUser` state

When you pass an _Signal Accessor_ into the query definition, it will auto-fetch, invalidate,
and cache the result when the signal Accessor updates. This means, with this design
**mutations are not neccessary** - but still strongly recommended.

## Optimistically Updating Query Data

When you want to perform an action related to a query, you utilize a mutation factory via [`createMutation`](/docs/signals/create-mutation).

When combined with `query.key`, this factory will automagically sync and update the query if it is listed in the `invalidate` options.

Even more, when combined with `onMutate/onSetData`, the UI will optimistically update while the query _runs in the background_ creating a "real-time" like experience in the UI.


```tsx
Example not found
```

<br />

Here's what's happening in this demo:

1. A query factory is created
2. A mutation factory is created
   a. `onMutate/setQueryData` provides optimistic updates to the `query`
   b. `invalidate` breaks the `query` cache to ensure the latest data is fetched in the background
3. The UI is automagically synced with the query data
4. Actions call the `mutate` helper to trigger mutations.

## Server Component Pattern

In an SSR environment, you execute the factory's **raw fetcher directly**, bypassing the reactive cache. Then, you pass that data down to your Client Components to "hydrate" or seed the Cerberus cache, ensuring the client doesn't double-fetch on mount.

This is the standard SSR pattern for React.

### 1. Server Component (Fetching)

Expose the raw, stateless fetcher function from your factory. You simply await it like a standard asynchronous function.


```tsx
Example not found
```


### 2. Client Component

On the client side, use the `initialData` property. If the Cerberus cache is empty, it will instantly seed the cache with the server's data, skipping the `<Suspense>` boundary entirely.


```tsx
Example not found
```


## Streaming Reponses (Async Generators)

Cerberus queries also support streaming data via [Async Generators](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AsyncGenerator). This is powerful if you are using an LLM API or your local API supports data streaming.


```tsx
Example not found
```


---
## on-cleanup

---
title: Cleanup Effects
description: Learn how to register cleanup functions to effects.
package: 'signals'
---







```tsx
// Source available in static configuration: {DEMOS.cleanupMeta}
```


## Usage

The `onCleanup` primitive is an essential memory-management tool within the Cerberus Signals reactivity system. It allows you to register a callback function that will execute right before a reactive context (like `createEffect` or `createComputed`) re-evaluates, or when that context is permanently destroyed.

This is the signal-based equivalent of returning a cleanup function in React's useEffect, but with significantly more flexibility.

`onCleanup` works within the scope of either:

1. [`createEffect`](/docs/signals/create-effect)
2. [`createComputed`](/docs/signals/create-computed)

In this example, we ensure a timer is cleared when it's parent effect is destroyed.


```tsx
Example not found
```


## When to use

Whenever an effect re-runs, any side effects from its previous run (like event listeners, intervals, or network requests) must be disposed of, or your application will suffer from severe memory leaks and race conditions.

Unlike React, where you must return a single cleanup function at the very end of your hook, `onCleanup` can be called anywhere inside your reactive scope, even deeply nested inside helper functions.

1. **DOM Subscriptions**: Removing `window` or `document` event listeners when the dependencies change.
2. **Timer Management**: Clearing `setTimeout` or `setInterval` cycles.
3. **Network Cancellation**: Triggering an `AbortController` to cancel stale network requests if a user rapidly clicks a button.
4. **Composable Helpers**: Building custom reactive utilities that manage their own memory cleanup without forcing the consumer to manually handle it.

## API

`onCleanup` accepts a callback function and operates functionally the same at `createEffect` and `createComputed`.


---
## overview

---
title: Signals Overview
description: An extremely lightweight and blazing fast fine-grain reactivity system for React.
package: 'signals'
---





## What is Signals?

The architectural landscape of frontend state management in 2026 reflects a
fundamental tension between React’s top-down, component-based reconciliation model
and the industry’s growing demand for fine-grained, localized reactivity. While
React continues to dominate the enterprise ecosystem, powering over 79 million
websites worldwide, its reliance on the Virtual DOM (VDOM) for state synchronization
introduces inherent performance bottlenecks at scale.

Cerberus Signals fills the gap that current external libraries have missed by
creating a fine-grained, ultra-lightweight, approach that out-performs in all areas
with an easy to use DX to provide full control and flexibility where you need.

## Installation


```bash
npm install @cerberus/signals@npm:@cerberus-design/signals
```


### Dependency Requirements

The Signals library only requires the use of React to be installed in your project.

## React

Our Signals library was built to ensure compatibility with React compiler and the
19+ API design. We have APIs that support both client and server rendering to meet
whichever need your use case might have.

## Typescript

Signals is built with typescript and provides additional meaningful type exports
in addition to the APIs. If any demo requires the use of the `use client` directive
you will see it displayed in the code preview.

## Server-side Rendering

Any API which uses the `createX` naming convention is server-side compatible.
Client-focused APIs are designed primarily as hooks to improve the developer experience
and overall understanding.


---
## reactive-text

---
title: Reactive Text
description: Learn how to read signals with fine-grained reactivity in React.
package: 'signals'
---








```tsx
// Source available in static configuration: {RDemos.meta}
```


## Usage

`ReactiveText` was created to provide fine-grained updates to the VDOM without
triggering component re-renders when the signal updates.

This allows React to function as close as possible to [SolidJS](https://docs.solidjs.com/quick-start)
where the JSX only renders once.

## Reading State

To render a signal, just pass the `Accessor` function to the `data` prop.

<NoteAdmonition
  description={
    <>
      The data prop expects either a String or Number value.
      <br />
      <br />
      To render complex lists, utilize the For component to loop through the content and then
      ReactiveText to display specific signal nodes.
    </>
  }
/>


```tsx
Example not found
```


## API

`ReactiveText` accepts the following options:

| Params | Required           | Description                                 |
| ------ | ------------------ | ------------------------------------------- |
| `data` | `String \| Number` | The Accessor to watch and render in the UI. |


---
## reactivity

---
title: Signals Reactivity
description: Learn the fundamentals of fine-grained reactivity with signals.
package: 'signals'
---






## Introduction

Reactivity powers the interactivity in React applications. This programming
paradigm refers to a system's ability to respond to changes in data or state
automatically.

In React, this is _false positive_ **natively built into the JSX render engine**.
This means, when state changes, React "re-renders" any component that either _defines_ or _consumes_ it. Ultimately, the "reactivity" is just a component function being called over and over (e.g., false positive).

**Cerberus Signals remove that constraint** and provides a way to control the
_define_ and _consume_ state without causing re-renders when updates happen (e.g., true reactivity).

### Primitives vs. Hooks

Cerberus Signals comes with two flavors of APIs: **Primitives** and **Hooks**.

Each API type will yield an intentional different result to keep the library flexible where you may need in your application.

> **Note:** We recommend defaulting to primtives. They are more flexible and provide fine-grained outcomes.

#### Primitives

Primitives are functions **that can be called in any location and scope**.

It doesn't matter if you are using it on the global scope, in your component, in a callback, React effect, or even a Node script. _There are no boundaries to primitives._

Primitives live outside of the React scope and **do not trigger component re-renders**.

#### Hooks

Hooks are React functions that are **restricted to a component scope**.

You know the rules: top level only - React knows about it.

Hooks live inside of the React scope and **_do_ trigger component re-renders**.

This example shows how both the primitve and hook APIs affect a component render-cycle:


```tsx
Example not found
```

<br />

Here the Demo component will re-render only on _updates_. However, the `ReactiveText`
component will **never** re-render on updates to ensure **fine-grained** reactivity.

This is just one of many ways to achieve fine-grained reactivity with Cerberus Signals.

## Reactive Principles

There are two core elements in a reactive system: [Signals](#signals) and [Subscribers](#subscribers).

### Signals

Signals serve as core elements in reactive systems, playing an important role in
data management and system responsiveness. They are responsible for storing and
managing data, as well as triggering updates across the system.

This is done through the use of _accessors_ (a.k.a. getters) and _setters_.


```tsx
Example not found
```

<br />

- **Accessor**: A _function_ responsible for getting the current value of the signal. You call a getter to access the data stored in a signal within a component.
- **Setter**: The function used to modify a signal's value. To trigger reactive updates across an application, you call a setter to update the value of a signal.

There are two ways to create signals:

- `createSignal`: create signals outside of components in any scenario
- `useSignal`: create signals inside of components

### Subscribers

Subscribers are the other core element in reactive systems. They are responsible
for tracking changes in signals and updating the system accordingly. They are
automated responders that keep the system up-to-date with the latest data changes.

Most importantly: **this lives outside of the React render engine**

This enables Cerberus Signals to allow creating global, local, external/local
component state updates without affecting the VDOM renders.

Subscribers work based on two main actions:

- **Observation**: At their core, subscribers observe signals. This keeps the subscriber primed to pick up on any changes to the signal they are tracking.
- **Response**: When a signal changes, the subscriber is notified. This triggers the subscriber to respond to the change in the signal. This can involve tasks like updating the UI or calling external functions.

There are multiple APIs that subscribe to signals:

- [`createEffect`](/docs/signals/create-effect): watch for state updates without affecting the React lifecycle
- [`createComputed`](/docs/signals/create-computed): compute a new value based on other signals.
- [`batch`](/docs/signals/batch): batch signal updates
- Any query or query related API

## Synchronous Reactivity

[Synchronous](https://developer.mozilla.org/en-US/docs/Glossary/Synchronous) reactivity
is Cerberus' default reactivity mode, where a system responds to changes in a
direct and linear fashion. When a signal changes, any corresponding subscribers
are immediately updated in an ordered manner.

With synchronous reactivity, the system is able to respond to changes in a predictable
manner. This is useful in scenarios where the order of updates is important. For
example, if a subscriber depends on another signal, it is important that the
subscriber is updated after the signal it depends on.


```tsx
Example not found
```

<br />

In this example, the `double` signal will always be updated after `count` due to
synchronous reactivity. This ensures that `double` is always up-to-date with the
latest value of `count`.

## Nesting Signals

Because signals are subscription-based, it opens the doors to news ways of thinking about state management. For example, you _could_ nest Signals if you wanted to. Everything is subscribed vs. React state which just updates because a function is re-run from top to bottom (fake reactivity).

> **Note:** We do not recommend using this pattern. This is just an informative note to show that Signals are more powerful that React state. It would be better to use other primitives devoted to this like createComputed.


```tsx
Example not found
```


---
## stores

---
title: Global Stores
description: Learn the fundamentals of creating signal-based stores in React Signals.
package: 'signals'
---






## Introduction

As your app grows you may find the need for a single-source of truth for managing
signals in a scalable way. In Cerberus Signals you can achieve this by creating
a store.

A store is simply a function that contains mutliple signals and actions which
manage those signals. There are no restrictions for what a store is.

**A store can use any primitive API in it**. This means the potential is limitless
for whatever you wish to achieve in a high-performant way that doesn't involve
React controlling the scenario.

## Global Stores

To create a global store, simply create a function that returns an Object. It can
be anything and use any Cerberus Signals Primitive API within it.


```tsx
Example not found
```


## Contextual Stores

To create a store that uses unique instances on a React app/component level, use
the [`createStoreContext`](/docs/signals/create-store-context) API.


```tsx
Example not found
```


## React rules

Depending on the complexity and use case of your store, React may "get in the way" of your signal management when using stores **within a component**.

If you intend on using a store within a component you must follow one of the two designs to ensure React doesn't corrupt your hard work via the render cycles:

### Pure Global Stores

If you have a store that can be called on the global scope (**outside of a component**), then you are good to go. Utilize `useRead` for iteration and `ReactiveText` for reading.


```tsx
Example not found
```


### Local Component Store

If a store **must live within a component**, then you will need to take precautions to ensure React does not corrupt your store state via wrapping your store in [`useStore`](/docs/signals/use-store).


```tsx
Example not found
```


## Reactivity

Since stores are essentially a primitive that contain primitives, you will need
to utilize the `ReactiveText` or `useRead` APIs in order to obtain the reactive
values within the scope of any component.

When calling a store **within a component** and reading a value with `useRead` you must wrap your store in `useStore` to ensure React does not corrupt the signal state.


---
## untrack

---
title: Untrack Signals
description: Learn how to read signals without subscribing to updates.
package: 'signals'
---







```tsx
// Source available in static configuration: {DEMOS.meta}
```


## Usage

The `untrack` primitive allows you to read the current value of a signal inside a reactive context (like `createEffect`, `createComputed`, or a React render phase) without subscribing to that signal.

This prevents unwanted re-evaluations, React infinite loops, and over-subscribing to state changes.

In this example, we update a signal and show the latest result (tracked) and what the untracked version is.


```tsx
Example not found
```


## When to use

By default, any signal read inside a tracking context will automatically bind to it. When that signal updates, the context re-runs. However, there are common scenarios where you only want to read the data, not react to it:

1. **Logging or Analytics**: You want to fire an analytics event when `userSignal` changes, but you need to include the `themeSignal` value in the payload without re-firing the event when the theme changes.
2. **Preventing Infinite Loops**: You need to conditionally initialize or mutate state based on the current value of a cache, without accidentally subscribing the surrounding component to the cache's internal lifecycle.
3. **Optimizing Component Renders**: In React integrations, bypassing unnecessary subscriptions keeps your component from re-rendering _O(1)_ updates that don't affect the DOM.

## Best Practices

- **Keep it synchronous**: `untrack` only disables tracking for the synchronous execution of the callback. If you use `await` inside the callback, signals read after the `await` might resume tracking depending on the environment context.
- **Keep it targeted**: Wrap only the specific signal reads you want to isolate. Wrapping entire large blocks of logic can lead to accidentally missing subscriptions you actually intended to track.

## API

`untrack` accepts an `Accessor` signal and returns the unsubscribed value at the time of calling.


---
## use-mutation

---
title: Using Mutations
description: Learn how to use defined mutations in React.
package: 'signals'
---







```tsx
// Source available in static configuration: {DEMOS.useMutationMeta}
```


## Usage

`useMutation` allows you to use a mutation factory (via [`createMutation`](/docs/signals/create-mutation)) within the scope of a React component.

Mutations's allow you to update the state of a query and have built in support for `Suspense` and Error Boundaries with no extra effort.

When utilizing the `invalidate` option, a query will automagically update once the mutation has resolved. Combing this with `onMutate/setQueryData` will create optimistic updates in the UI.

## Using Mutations

To use a mutation call the `mutate` method from the return Object.


```tsx
Example not found
```


## Data

The `data` property contains the returned value of the mutation. This is not necessary for UI updates as mutations were designed to update querys on your behalf through invalidation.


```tsx
Example not found
```


## Status

The `status` property is the lifecycle state associated with the mutation. To learn more about mutation lifecycles, see the [create mutation docs](/docs/signals/create-mutation).


```tsx
Example not found
```


## API

`useMutation` accepts the following options:

| Params          | Required | Description                                |
| --------------- | -------- | ------------------------------------------ |
| `MutationTuple` | Yes      | The value of the defined mutation factory. |

### Return

`useMutation` returns and Object with the following options:

| Property | Type                           | Description                                         |
| -------- | ------------------------------ | --------------------------------------------------- |
| `mutate` | `(variables: V) => Promise<T>` | A function that calls the defined mutation Promise. |
| `status` | `MutationStatus`               | The Promise-based status state of the mutation.     |
| `data`   | `T \| undefined`               | The cached state of the query associated with it.   |
| `error`  | `unknown \| undefined`         | The error thrown from the mutation.                 |


---
## use-query

---
title: Using Queries
description: Learn how to used defined queries in React.
package: 'signals'
---







```tsx
// Source available in static configuration: {DEMOS.useQueryMeta}
```


## Usage

`useQuery` allows you use a query factory (via [`createQuery`](/docs/signals/create-query))
within the scope of a React component.

The return of `useQuery` is a **read-only** value which is the result of the query fetcher.

Query's have built in support for `Suspense` and Error Boundaries with no extra effort.

## Using Queries

To use query factories within React components, simply pass in the defined query to the hook and bind
the value in your JSX.


```tsx
Example not found
```


## Initial Data

If you would like to bypass the initial fetch with pre-loaded data that matches the return of the query factory being used (e.g., parent server component fetch) - add and options Object as the last argument with the property `initialData`.


```tsx
Example not found
```


## With Suspense

To utilize the native React `Suspense` API with your query, wrap the parent
of the component using the query in `Suspense` as per requirements of the React
API.

To learn more about `Suspense`, [read the React docs](https://react.dev/reference/react/Suspense).

## With Error Boundaries

If a query errors out, `createQuery` will throw an error that will natively trigger
an Error Boundary if you have one established.

To learn more about Error Boundaries, see the [Error Boundary library on NPM](https://www.npmjs.com/package/react-error-boundary).

## API

`useQuery` accepts the following options:

| Params                    | Required | Description                                                        |
| ------------------------- | -------- | ------------------------------------------------------------------ |
| `Accessor<QueryState<T>>` | Yes      | The query to utilize.                                              |
| `QueryOptions<T>`         | No       | [Additional options](#query-options) to use for the query factory. |

### Return

`useQuery` returns the value of the Promise defined in `createQuery`.

### Query Options

The `QueryOption` Object contains the following properties:

| Params        | Required | Description                                                                                      |
| ------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `initialData` | No       | When provided will bypass the initial query fetch and instead return the value of `initialData`. |


---
## use-read

---
title: Reading Primitive Signals
description: Learn how to read primivite signals in React components.
package: 'signals'
---








```tsx
// Source available in static configuration: {RDemos.readMeta}
```


## Usage

When you want to read a signal value within a component _without having fine-grained
reactivity_.

> **Note:** This is an alternative API to ReactiveText and should only be used in very specific use cases.

## Reading State

The `useRead` hook was created to provide low-level access control for signals.
By utilizing this hook, you are **opting out of fine-grained** reactivity and other
performance enhancing benefits.

> **Note:** This API should be used sparingly and only for very specific use cases where you know what you are doing.


```tsx
Example not found
```


> **Note:** We always recommend utilizing ReactiveText over useRead to provide better control over React rendering in addition to a cleaner DX.

## API

`useRead` accepts the following options:

| Params     | Required | Description                                |
| ---------- | -------- | ------------------------------------------ |
| `accessor` | `true`   | The signal Accessor value to subscribe to. |

### Return

`useRead` returns the latest value of the signal Accessor.


---
## use-signal

---
title: Using Signals
description: Learn how to use signals within the React render context.
package: 'signals'
---







```tsx
// Source available in static configuration: {DEMOS.hookMeta}
```


## Usage

When you want to create a signal **within the React render** context which triggers re-renders.

There are two ways to read a signal from `useSignal`:

1. Using the non-accessor value
2. Combining the `Accessor` with `ReactiveText` for fine-grained reactivity

## Basic State

`useSignal` is a more reliable version of `useState` that includes an additional `Accessor` as the third Tuple item.


```tsx
Example not found
```


## Reading State

There are two ways to read the signal value based on your preferred method:

1. Using the first value: the latest accessor result
2. Using the third value: the pure accessor function

Both options are valid and more performant than native React state. However, only
the _pure accessor_ can be passed into `ReactiveText`.


```tsx
Example not found
```


## Setting State

With Cerberus Signals, how you set the state no longer matters. You are free to
use mutation or immutability. Both results will yield the same high performant and
reliable reactivity.

The second value of the Tuple is the `Setter` function.

The setter API is the exact same as the `createSignal` Setter and accepts any type
of setting value or callback.


```tsx
Example not found
```


## `useSignal` vs. `useState`: The "Stale Closure" Killer

React's `useState` traps values in closures. This is the root cause of 90% of React bugs. If you use `useState` inside a `setInterval`, an event listener, or an async fetch block, it will read the old, stale value from when the component first rendered.

To fix it, you have to juggle `useRef` and complex `useEffect` dependency arrays.

`useSignal` completely destroys this problem because it returns a getter Accessor function as the third option in the Tuple:


```tsx
Example not found
```


### Separation of State and Lifecycle

With `useState`, the state is glued to the component. If the component unmounts, the state dies.

With `useSignal`, the state lives in the external reactive graph, and `useRead` just "peeks" at it. This means you can trigger complex business logic (`createEffect`, `createComputed`) completely outside of React's render cycle.

If `setLocal` updates the signal, it instantly triggers any pure-JS `createEffect` you have listening to it, synchronously, before React even begins its slow VDOM render phase.

## API

`useSignal` accepts the following options:

| Params         | Required | Description                                |
| -------------- | -------- | ------------------------------------------ |
| `initialValue` | `false`  | The initial value to set for the accessor. |

### Return

`useSignal` returns a `SignalTuple<T>` Array of the following values:

| Index | Type          | Description                                           |
| ----- | ------------- | ----------------------------------------------------- |
| 0     | `T`           | The latest value of the accessor.                     |
| 1     | `Setter<T>`   | A function to update the signal value.                |
| 2     | `Accessor<T>` | A function that returns the latest value when called. |


---
## use-store

---
title: Using Store Instances
description: Learn how to use instances of stores as an alternative to Context.
package: 'signals'
---







```tsx
// Source available in static configuration: {DEMOS.storeMeta}
```


## Usage

When you want to use a **unqiue instance** of a global [Store](/docs/signals/stores) but do not need a [Context API](/docs/signals/create-store-context).

## Using the Store

Simply pass in a store to the `useStore` hook and recieve a memoized version of it - protected against re-renders.


```tsx
Example not found
```

<br />

For more information about stores, see the [Stores page](/docs/signals/stores).

## API

`useStore` accepts the following options:

| Params  | Required | Description                           |
| ------- | -------- | ------------------------------------- |
| `store` | Yes      | The store function reference to call. |

### Return

`useStore` returns a memoized version of the store value (e.g., what the store returns);


---
## animation-styles

---
title: Animation Styles
description:
  Learn how to use animation styles to define reusable motion properties.
---





## Overview

Animation styles allow you to define reusable animation properties. The goal is
to reduce the amount of code needed to animate components.

The supported animation styles are:

- **Animation**: animation composition, delay, direction, duration, fill mode,
  iteration count, name, play state, timing function

- **Animation range**: animation range, start, end, timeline

- **Transform origin**: transform origin

## Defining animation styles

Animation styles are defined using the `defineAnimationStyles` function.

Here's an example of an animation style:

```ts title="animation-styles.ts"


const animationStyles = defineAnimationStyles({
  bounceFadeIn: {
    value: {
      animationName: "bounce, fade-in",
      animationDuration: "1s",
      animationTimingFunction: "ease-in-out",
      animationIterationCount: "infinite",
    },
  },
})
```

## Built-in animation styles

Cerberus provides a set of built-in animation styles that you can use.

<AnimationStylesDemo />

> **Note:** You can change the direction of some animations by using the `data-placement` attribute with the value of: top,bottom,left, or right.

## Update the theme

To use the animation styles, update the `theme` object with the
`animationStyles` property.

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


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

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

  theme: {
    extend: {
      animationStyles,
    },
  }
})
```

## Using animation styles

Now you can use `animationStyle` property in your components.

```tsx
<Box
  data-state="open"
  animationDuration="slow"
  animationStyle={{ _open: "slide-fade-in", _closed: "slide-fade-out" }}
>
  This content will fade in
</Box>
```

## JSX Patterns

To make using animations even easier, Cerberus provides JSX patterns for all built-in animation styles. You can use these patterns to quickly apply animations to your components.

}>
```tsx


<EmphasizedSlideIn>
  <Box>This content will slide in with emphasis</Box>
</EmphasizedSlideIn>
```


---
## background

---
title: Background
description:
  JSX style props for styling background colors, gradients, and images.
---

## Background Attachment

Use `bgAttachment` to control the attachment of a background image.

```tsx
<Box bgAttachment="fixed" bgImage="url(...)" />
```

| Prop                                   | CSS Property            | Token Category |
| -------------------------------------- | ----------------------- | -------------- |
| `bgAttachment`, `backgroundAttachment` | `background-attachment` | -              |

## Background Blend Mode

Use `bgBlendMode` prop to control how an element's background image should blend
with the its background color.

```tsx
<Box bgBlendMode="multiply" bgColor="red.200" bgImage="url(...)" />
```

## Background Clip

Use `bgClip` to control the clipping of a background image.

```tsx
<Box bgClip="border-box" bgImage="url(...)" />
```

| Prop                       | CSS Property      | Token Category |
| -------------------------- | ----------------- | -------------- |
| `bgClip`, `backgroundClip` | `background-clip` | -              |

## Background Color

Use `bg`, `bgColor`, or `backgroundColor` props to set the background color of
an element.

```tsx
<Box bg="red.200" />
<Box bgColor="red.200" />

// with opacity modifier
<Box bg="blue.200/30" />
<Box bgColor="blue.200/30" />
```

| Prop                         | CSS Property       | Token Category |
| ---------------------------- | ------------------ | -------------- |
| `bg`, `background`           | `background`       | `colors`       |
| `bgColor`, `backgroundColor` | `background-color` | `colors`       |

## Background Origin

Use `bgOrigin` or `backgroundOrigin` to control the origin of a background
image.

```tsx
<Box bgOrigin="border-box" bgImage="url(...)" />
```

| Prop                           | CSS Property        | Token Category |
| ------------------------------ | ------------------- | -------------- |
| `bgOrigin`, `backgroundOrigin` | `background-origin` | -              |

## Background Position

Properties for controlling the src and position of a background image.

```tsx
<Box bgImage="url(...)" bgPosition="center" />
```

| Prop                                 | CSS Property       | Token Category |
| ------------------------------------ | ------------------ | -------------- |
| `bgPosition`, `backgroundPosition`   | `background-image` | -              |
| `bgPositionX`, `backgroundPositionX` | `background-image` | -              |
| `bgPositionY`, `backgroundPositionY` | `background-image` | -              |

## Background Repeat

Use `bgRepeat` or `backgroundRepeat` to control the repeat of a background
image.

```tsx
<Box bgRepeat="no-repeat" bgImage="url(...)" />
```

| Prop                           | CSS Property        | Token Category |
| ------------------------------ | ------------------- | -------------- |
| `bgRepeat`, `backgroundRepeat` | `background-repeat` | -              |

## Background Size

Use `bgSize` or `backgroundSize` to control the size of a background image.

```tsx
<Box bgSize="cover" bgImage="url(...)" />
```

| Prop                       | CSS Property      | Token Category |
| -------------------------- | ----------------- | -------------- |
| `bgSize`, `backgroundSize` | `background-size` | -              |

## Background Image

Use `bgImage` or `backgroundImage` to set the background image of an element.

```tsx
<Box bgImage="url(...)" />
<Box bgImage="radial-gradient(circle, #0000 45%, #000f 48%)" />
<Box bgImage="linear-gradient(black, white)" />

// with token reference
<Box bgImage="linear-gradient({colors.red.200}, {colors.blue.200})" />
```

| Prop                         | CSS Property       | Token Category        |
| ---------------------------- | ------------------ | --------------------- |
| `bgImage`, `backgroundImage` | `background-image` | `assets`, `gradients` |

## Background Gradient

Properties to create a background gradient based on color stops.

```tsx
<Box bgGradient="to-r" gradientFrom="red.200" gradientTo="blue.200" />
```

| Prop           | CSS Property       | Token Category |
| -------------- | ------------------ | -------------- |
| `bgGradient`   | `background-image` | `gradients`    |
| `textGradient` | `background-image` | `gradients`    |
| `gradientFrom` | `--gradient-from`  | `colors`       |
| `gradientTo`   | `--gradient-to`    | `colors`       |
| `gradientVia`  | `--gradient-via`   | `colors`       |


---
## border

---
title: Border
description: JSX style props for styling border and border radius.
---

## Border Radius

### All sides

Use the `rounded` or `borderRadius` props to apply border radius on all sides of
an element.

```tsx
<Box borderRadius="md" />
<Box rounded="md" /> // shorthand
```

| Prop                      | CSS Property    | Token Category |
| ------------------------- | --------------- | -------------- |
| `rounded`, `borderRadius` | `border-radius` | `radii`        |

### Specific sides

Use the `rounded{Left,Right,Top,Bottom}` or
`border{Left,Right,Top,Bottom}Radius` prop, to apply border radius on a specific
side of an element.

```tsx
<Box borderTopRadius="md" />
<Box roundedTop="md" /> // shorthand

<Box borderLeftRadius="md" />
<Box roundedLeft="md" /> // shorthand
```

Use the logical equivalent to make the border radius adapt based on the text
direction.

```tsx
<Box roundedStart="md" />
<Box roundedEnd="md" />
```

| Prop                                  | CSS Property                                           | Token Category |
| ------------------------------------- | ------------------------------------------------------ | -------------- |
| `roundedLeft`, `borderLeftRadius`     | `border-left-radius`                                   | `radii`        |
| `roundedRight`, `borderRightRadius`   | `border-right-radius`                                  | `radii`        |
| `roundedTop`, `borderTopRadius`       | `border-top-radius`                                    | `radii`        |
| `roundedBottom`, `borderBottomRadius` | `border-bottom-radius`                                 | `radii`        |
| `roundedStart`, `borderStartRadius`   | `border-start-start-radius`, `border-end-start-radius` | `radii`        |
| `roundedEnd`, `borderEndRadius`       | `border-start-end-radius`, `border-end-end-radius`     | `radii`        |

### Specific corners

Use the `border{Top,Bottom}{Left,Right}Radius` properties, or the shorthand
equivalent to round a specific corner.

```tsx
<Box borderTopLeftRadius="md" />
<Box roundedTopLeft="md" /> // shorthand
```

Use the logical properties to adapt based on the text direction.

```tsx
<Box borderStartStartRadius="md" />
<Box roundedStartStart="md" /> // shorthand
```

| Prop                                     | CSS Property                 | Token Category |
| ---------------------------------------- | ---------------------------- | -------------- |
| `roundedTopLeft`,`borderTopLeftRadius`   | `border-top-left-radius`     | `radii`        |
| `roundedTopRight`,`borderTopRight`       | `border-top-right-radius`    | `radii`        |
| `roundedBottomRight`,`borderBottomRight` | `border-bottom-right-radius` | `radii`        |
| `roundedBottomLeft`,`borderBottomLeft`   | `border-bottom-left-radius`  | `radii`        |

## Border Width

### All sides

Use the `borderWidth` prop to apply border width on all sides of an element.

```tsx
<Box borderWidth="1px" />
```

| Prop          | CSS Property   | Token Category |
| ------------- | -------------- | -------------- |
| `borderWidth` | `border-width` | `borderWidths` |

### Specific sides

Use the `border{Left|Right|Top|Bottom}Width` prop to apply border width on a
specific side of an element.

```tsx
<Box borderTopWidth="1px" />
<Box borderLeftWidth="1px" />
```

Use the logical equivalent to make the border width adapt based on the text
direction.

```tsx
<Box borderInlineStartWidth="1px" />
<Box borderInlineWidth="1px" /> // shorthand
```

| Prop                                          | CSS Property                | Token Category |
| --------------------------------------------- | --------------------------- | -------------- |
| `borderTopWidth`                              | `border-top-width`          | `borderWidths` |
| `borderLeftWidth`                             | `border-left-width`         | `borderWidths` |
| `borderRightWidth`                            | `border-right-width`        | `borderWidths` |
| `borderBottomWidth`                           | `border-bottom-width`       | `borderWidths` |
| `borderStartWidth` , `borderInlineStartWidth` | `border-{start+end}-width`  |
| `borderEndWidth` , `borderInlineEndWidth`     | `border-{start+end}-width`  |
| `borderXWidth` , `borderInlineWidth`          | `border-{left,right}-width` | `borderWidths` |
| `borderYWidth` , `borderBlockWidth`           | `border-{top,bottom}-width` | `borderWidths` |

## Border Color

### All sides

Use the `borderColor` prop to apply border color on all sides of an element.

```tsx
<Box borderColor="red.400" />

// with opacity modifier
<Box borderColor="red.400/20" />
```

### Specific sides

Use the `border{Left,Right,Top,Bottom}Color` prop to apply border color on a
specific side of an element.

```tsx
<Box borderTopColor="red.400" />
<Box borderLeftColor="red.400" />
```

Use the logical properties to adapt based on the text direction.

```tsx
<Box borderStartColor="red.400" />
<Box borderEndColor="red.400" />
```

| Prop                                          | CSS Property               | Token Category |
| --------------------------------------------- | -------------------------- | -------------- |
| `borderColor`                                 | `border-color`             | `colors`       |
| `borderTopColor`                              | `border-top-color`         | `colors`       |
| `borderLeftColor`                             | `border-left-color`        | `colors`       |
| `borderRightColor`                            | `border-right-color`       | `colors`       |
| `borderBottomColor`                           | `border-bottom-color`      | `colors`       |
| `borderStartColor` , `borderInlineStartColor` | `border-{start,end}-color` | `colors`       |
| `borderEndColor` , `borderInlineEndColor`     | `border-{start,end}-color` | `colors`       |
| `borderXColor`, `borderInlineColor`           | `border-inline-color`      | `colors`       |
| `borderYColor`, `borderBlockColor`            | `border-block-color`       | `colors`       |

## Divide Width

Use the `divide{X,Y}Width` prop to apply border width between elements. It uses
the CSS selector `> * + *` to apply the `border*` properties.

```tsx
<Box divideXWidth="1px">
  <Box>1</Box>
  <Box>2</Box>
</Box>

<Box divideYWidth="1px">
  <Box>1</Box>
  <Box>2</Box>
</Box>
```

| Prop          | CSS Property                        | Token Category |
| ------------- | ----------------------------------- | -------------- |
| `divideWidth` | `border-{inline,block}-start-width` | `borderWidths` |

## Divide Color

Use the `divideColor` prop to apply border color between elements.

```tsx
<Box divideColor="red.400">
  <Box>1</Box>
  <Box>2</Box>
</Box>
```

| Prop          | CSS Property     | Token Category |
| ------------- | ---------------- | -------------- |
| `divideColor` | `--divide-color` | `colors`       |

## Divide Style

Use the `divideStyle` prop to apply border style between elements.

```tsx
<Box divideX="2px" divideStyle="dashed">
  <Box>1</Box>
  <Box>2</Box>
</Box>
```

| Prop          | CSS Property     | Token Category |
| ------------- | ---------------- | -------------- |
| `divideStyle` | `--divide-style` | `borderStyle`  |


---
## cascade-layers

---
title: Cascade Layers
description:
  CSS cascade layers refer to the order in which CSS rules are applied to an
  HTML element.
---

Cerberus relies on CSS cascade layers to provide a predictable, performant way
to override components. The layers are defined to match that of
[Panda CSS](https://panda-css.com).

## Layer Types

Cerberus supports these cascade layer types:

- `@layer reset`: Where the preflight or css resets styles are defined.

- `@layer base`: Where global styles are placed when defined in `globalCss`
  config property.

- `@layer recipes`: Where styles for recipes are placed when defined in
  `theme.recipes` or `theme.slotRecipes`

- `@layer tokens`: Where styles for design tokens are placed when defined in
  `theme.tokens` or `theme.semanticTokens`

- `@layer utilities`: Where styles for utilities are placed when defined in
  `theme.utilities`

## Layer Order

Cerberus recommends the following order for cascade layers:

```css
@layer reset, base, tokens, recipes, utilities;
```

This structure allows for smoother experience when combining Cerberus and Panda
CSS in the same project.


---
## cerberus-factory

---
title: Cerberus Factory
description: Learn about the Cerberus Factory, a powerful tool for managing styles and themes in the Cerberus Design System.
---

## Overview

Cerberus factory serves as a way to create supercharged JSX component from any
HTML element to enable them receive `asChild`, `css`, and style props.

```js

```

## JSX Element

With the JSX factory, you can use `cerberus.<element>` syntax to create JSX elements that support `css`, `asChild`, and style props.

```tsx


function Example() {
  return (
    <cerberus.button
      bgColor="black"
      _hover={{
        bgColor: 'blue'
      }}
      css={{
        '&:is([data-custom])': {
          color: 'red'
        }
      }}
    >
      Click me
    </cerberus.button>
  )
}
```

## Factory function

Use the `cerberus` function to convert native element components.

```tsx
const Link = cerberus("a")

function Example() {
  return <Link css={{ color: 'blue' }} href="https://chakra-ui.com" />
}
```

## Creating Primitives

You can create a Cerberus primitive with the `createCerberusPrimitive` function. This is useful for creating components that have a specific recipe or style.

All primitives created with any of the higher order functions it returns will also have the factory props available.

Additionally, you may pass in any reference to an Element or a string name of a HTML element for your component.

### withNoRecipe

Creates a Cerberus component with bare features and no recipe. This is identical to using the `cerberus` function directly.

```tsx


const { withNoRecipe } = createCerberusPrimitive()

const Button = withNoRecipe(cerberus.button)

function Example() {
  return <Button color="blue">Click me</Button>
}
```

### withRecipe

Creates a Cerberus component with a specific recipe applied. This allows you to use the styles defined in the recipe.

```tsx



const { withRecipe } = createCerberusPrimitive(button)
const Button = withRecipe('button')

function Example() {
  return <Button css={{ color: 'blue' }}>Click me</Button>
}
```

This example creates a Cerberus button component that has the `button` recipe styles applied to it (along with Cerberus component features).

### withSlotRecipe

Creates a Cerberus component with a specific recipe applied at the slot level. This is useful for creating components that have multiple slots with different styles.

```tsx



const { withSlotRecipe } = createCerberusPrimitive(field)

const Field = withSlotRecipe("div", "root")
const FieldLabel = withSlotRecipe("label", "label")
const FieldInput = withSlotRecipe("input", "input")

function Example() {
  return (
    <Field css={{ color: 'blue' }}>
      <FieldLabel>Label</FieldLabel>
      <FieldInput type="text" />
    </Field>
  )
}
```

In this example, we create a Cerberus field component with a root slot, label slot, and input slot. Each slot can have its own styles defined in the recipe, and utilize the Cerberus factory features when needed.

## Polymorphism

Every component created with the Cerberus factory can accept the
`asChild` props to change the underlying DOM element.

```tsx
<Button asChild>
  <a href="https://cerberus.digitalu.design/">Cerberus</a>
</Button>
```


---
## color-opacity-modifier

---
title: Color opacity modifier
description: How to dynamically set the opacity of a raw color or color token
---

Every color related style property can use the
[`color-mix`](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/color-mix)
shortcut to apply opacity to a color.

## Syntax

The general syntax is `{color}/{opacity}`. For example: `bgColor="page.surface.100/40"`.

## Usage

```tsx
<Text bgColor="danger.bg.initial/40" color="danger.text.initial">
  Hello World
</Text>
```

This will generate something like this:

```css {2,3}
.css-sxdf {
  --mix-background: color-mix(in srgb, var(--colors-danger-bg-initial) 40%, transparent);
  background-color: var(--mix-background, var(--colors-danger-bg-initial));
  color: var(--colors-danger-text-initial);
}
```

### CSS Variables

This feature can be used in css variables as well. This is useful for creating
one-off color token in a component.

The token reference syntax `{}` is required for this to work.

```tsx
<Box css={{ "--bg": "{colors.danger.bg.initial/40}" }}>
  <Text>Hello World</Text>
  <Box bg="var(--bg)" />
</Box>
```


---
## conditional-styles

---
title: Conditional Styles
description: Learn how to apply conditional styles in Cerberus Design System
---



## Overview

Cerberus allows you to write styles for pseudo states, media queries, and custom
data attributes with the conditional style props.

<NoteAdmonition
  description={
    <>
      See the list of <a href="#reference">built-in conditions</a> below.
    </>
  }
/>

## Usage

For example, here's how to change the background color of a button when it's
hovered:

```tsx
<Box bg="danger.bg.initial" _hover={{ bg: 'danger.bg.hover' }}>
  Hover me
</Box>
```

### Nested condition

Conditional values can be nested to create complex selector rules.

Here's how to change the background color of an element when in focus on hover:

```tsx
<Box bg={{ base: 'danger.bg.initial', _hover: { _focus: 'danger.bg.hover' } }}>
  Hover & Focus me
</Box>
```

### At Rules

This also works with the supported at-rules (`@media`, `@layer`, `@container`,
`@supports`, and `@page`):

```tsx
<Box
  css={{
    '@container (min-width: 10px)': {
      color: 'success.surface.initial',
    },
  }}
>
  Hello
</Box>
```

## Pseudo Classes

### Hover, Active, Focus, and Disabled

Here's an example of how to style the hover, active, focus, and disabled states
of an element

```tsx
<Box
  _hover={{ bg: "danger.bg.hover" }}
  _active={{ bg: "danger.bg.active" }}
  _focus={{ bg: "danger.bg.initial" }}
  _disabled={{ opacity: "0.5" }}
>
  Hover me > Hover me
</Box>
```

### First, Last, Odd, Even

Here's an example of how to style the first, last, odd, and even elements in a
list

```tsx
<ul>
  <For each={items}>
    {(item) => (
      <li key={item}>
        <Box _first={{ color: 'danger.bg.initial' }} _last={{ color: 'red.800' }}>
          {item}
        </Box>
      </li>
    )}
  </For>
</ul>
```

You can also style even and odd elements using the `_even` and `_odd` modifier

```tsx
<Table.Root>
  <Table.Body>
    <For each={items}>
    {(item) => (
      <Table.Row key={item} css={{
        _even={{ bg: "gray.100" }}
        _odd={{ bg: "white" }}
      }}>
        <Table.Cell>{item}</Table.Cell>
      </Table.Row>
    )}
  </Table.Body>
</Table.Root>
```

## Pseudo Elements

### Before and After

To style the `::before` and `::after` pseudo elements of an element, use the
`_before` and `_after` modifiers

```tsx /_before/
<Box _before={{ content: '"👋"' }} _after={{ content: '"🥂"' }}>
  Hello
</Box>
```

### Placeholder

To style the placeholder text of any input or textarea, use the `_placeholder`
modifier:

```tsx {3}
<Input
  placeholder="Enter your name"
  css={{
    _placeholder={{ color: "gray.500" }}
  }}
/>
```

### File Inputs

To style the file input button, use the `_file` modifier:

```tsx {3}
<Input
  type="file"
  css={{
    _file={{ bg: "gray.500", px: "4", py: "2", marginEnd: "3" }}
  }}
/>
```

## Media Queries

### Reduced Motion

Use the `_motionReduce` and `_motionSafe` modifiers to style an element based on
the user's motion preference:

```tsx
<Box _motionSafe={{ transition: 'all 0.3s' }}>Hello</Box>
```

### Color Scheme

The `prefers-color-scheme` media feature is used to detect if the user has
requested the system to use a light or dark color theme.

Use the `_osLight` and `_osDark` modifiers to style an element based on the
user's color scheme preference:

```tsx
<Box bg={{ base: 'white', _osDark: 'black' }}>Hello</Box>
```

### Color Contrast

The `prefers-contrast` media feature is used to detect if the user has requested
the system use a high or low contrast theme.

Use the `_highContrast` and `_lessContrast` modifiers to style an element based
on the user's color contrast preference:

```tsx
<Box bg={{ base: 'white', _highContrast: 'black' }}>Hello</Box>
```

### Orientation

The `orientation` media feature is used to detect if the user has a device in
portrait or landscape mode.

Use the `_portrait` and `_landscape` modifiers to style an element based on the
user's device orientation:

```tsx
<Box pb="4" _portrait={{ pb: '8' }}>
  Hello
</Box>
```

## Selectors

### Arbitrary selectors

For arbitrary, use the `css` prop to write styles for one-off selectors:

```tsx
<Box css={{ '&[data-state=closed]': { color: 'red.300' } }} />
```

Here's another example that targets the child elements of a parent element:

```tsx
<Box
  css={{
    '& > *': { margin: '2' },
  }}
/>
```

### Group Selectors

To style an element based on its parent element's state or attribute, add the
`group` class to the parent element, and use any of the `_group*` modifiers on
the child element.

```tsx
<div className="group">
  <Text _groupHover={{ bg: 'danger.bg.initial' }}>Hover me</Text>
</div>
```

This modifier works for every pseudo class modifiers like `_groupHover`,
`_groupActive`, `_groupFocus`, and `_groupDisabled`, etc.

### Sibling Selectors

To style an element based on its sibling element's state or attribute, add the
`peer` class to the sibling element, and use any of the `_peer*` modifiers on
the target element.

```tsx /_peerHover={{ bg: "danger.bg.initial" }}/
<div>
  <p className="peer">Hover me</p>
  <Box _peerHover={{ bg: 'danger.bg.initial' }}>I'll change by bg</Box>
</div>
```

> **Note:** This only works for when the element marked with `peer` is a
> previous siblings, that is, it comes before the element you want to start.

## Data Attribute

### LTR and RTL

To style an element based on the direction of the text, use the `_ltr` and
`_rtl` modifiers

```tsx {2}
<div dir="ltr">
  <Box _ltr={{ ml: '3' }} _rtl={{ mr: '3' }}>
    Hello
  </Box>
</div>
```

> **Note:** PandaCSS automagically handles this when you use the [padding|margin]top/bottom/left/right properties by converting it to use the `inline` and `block`.

### State

To style an element based on its `data-{state}` attribute, use the corresponding
`_{state}` modifier

```tsx
<Box data-state="indeterminate" _indeterminate={{ bg: 'gray.500' }}>
  Hello
</Box>
```

This works for common states like `data-active`, `data-disabled`, `data-focus`,
`data-hover`, `data-invalid`, `data-required`, and `data-valid`.

```tsx /_active/
<Box data-active _active={{ bg: 'gray.500' }}>
  Hello
</Box>
```

### Orientation

To style an element based on its `data-orientation` attribute, use the
`_horizontal` and `_vertical` modifiers

```tsx
<Box
  data-orientation="horizontal"
  _horizontal={{ bg: 'danger.bg.initial' }}
  _vertical={{ bg: 'action.bg.initial' }}
>
  Hello
</Box>
```

## ARIA Attribute

To style an element based on its `aria-{state}=true` attribute, use the
corresponding `_{state}` prop

```tsx
<Box aria-expanded="true" _expanded={{ bg: 'gray.500' }}>
  Hello
</Box>
```

## Reference

Here's a list of all the condition props you can use in Cerberus:

Cerberus extends the [built-in conditions](https://panda-css.com/docs/concepts/conditional-styles#reference) provided by Panda-CSS.

| Name                | Selector                                                      |
| ------------------- | ------------------------------------------------------------- |
| `_cerberusTheme`    | `[data-theme=cerberus] &`                                     |
| `_acheronTheme`     | `[data-theme=acheron] &`                                      |
| `_lightMode`        | `[data-color-mode=light] &, &.light, .light &`                |
| `_darkMode`         | `[data-color-mode=dark] &, &.dark, .dark &`                   |
| `_open`             | `'&:is([open], [data-open], [data-state=open])'`              |
| `_closed`           | `'&:is([closed], [data-closed], [data-state=closed])'`        |
| `_notDisabled`      | `&:is(:not([disabled]), [data-disabled=false])`               |
| `_modalOpen`        | `&:is([data-modal-open=true])`                                |
| `_screenReaderOnly` | `&:is([data-screen-reader-only=true])`                        |
| `_isOver`           | `&:is([data-over=true])`                                      |
| `_isDropped`        | `&:is([data-dropped=true])`                                   |
| `_today`            | `&:is([data-today=true], [data-date=today])`                  |
| `_pastDay`          | `&:is([data-past-day=true], [data-date=past])`                |
| `_inRange`          | `&:is([data-in-range=true])`                                  |
| `_startRange`       | `&:is([data-start-range])`                                    |
| `_endRange`         | `&:is([data-end-range])`                                      |
| `_invalid`          | `&:is(:invalid, [data-invalid], [aria-invalid])`              |
| `_userInvalid`      | `&:is(:user-invalid, [aria-invalid])`                         |
| `_groupInvalid`     | `.group:is([data-invalid] &, [aria-invalid]) &`               |
| `_groupChecked`     | `.group:is([data-checked="true"] &, [aria-checked="true"]) &` |
| `_horizontal`       | `&:is([data-orientation=horizontal])`                         |
| `_vertical`         | `&:is([data-orientation=vertical])`                           |
| `_paused`           | `&:is([data-paused], [data-paused=true])`                     |
| `_reverse`          | `&:is([data-reverse], [data-reverse=true])`                   |
| `_sideBottom`       | `&:is([data-side=bottom])`                                    |
| `_sideTop`          | `&:is([data-side=top])`                                       |
| `_sideStart`        | `&:is([data-side=start])`                                     |
| `_sideEnd`          | `&:is([data-side=end])`                                       |
| `_positionBottom`   | `&:is([data-position=bottom])`                                |
| `_positionTop`      | `&:is([data-position=top])`                                   |
| `_positionLeft`     | `&:is([data-position=left])`                                  |
| `_positionRight`    | `&:is([data-position=right])`                                 |
| `_startIcon`        | `&:is([data-start-icon=true])`                                |
| `_button`           | `'& :where([data-scope=button])'`                             |
| `_icon`             | `'& :where(svg)'`                                             |
| `_iconButton`       | `'& :where([data-scope=icon-button])'`                        |
| `_menuTrigger`      | `'& :where([data-scope=menu][data-part=trigger])'`            |
| `_tooltip`          | `&:is([data-tooltip=true])`                                   |
| `_notify`           | `&:is([data-notify=true])`                                    |
| `_admin`            | `&:is([data-role=admin])`                                     |
| `_student`          | `&:is([data-role=student])`                                   |
| `_user`             | `&:is([data-role=user])`                                      |
| `_highlight`        | `&:is(::selection)`                                           |
| `_spellingError`    | `&:is(::spelling-error)`                                      |
| `_grammarError`     | `&:is(::grammar-error)`                                       |
| `_pagePalette`      | `&:is([data-palette=page])`                                   |
| `_actionPalette`    | `&:is([data-palette=action])`                                 |
| `_infoPalette`      | `&:is([data-palette=info])`                                   |
| `_successPalette`   | `&:is([data-palette=success])`                                |
| `_warningPalette`   | `&:is([data-palette=warning])`                                |
| `_dangerPalette`    | `&:is([data-palette=danger])`                                 |
| `_highEmphasis`     | `&:is([data-emphasis=high])`                                  |
| `_subtleEmphasis`   | `&:is([data-emphasis=subtle])`                                |
| `_lowEmphasis`      | `&:is([data-emphasis=low])`                                   |
| `_page`             | `'&:is([data-type=page], [data-type=loading])'`               |
| `_action`           | `&:is([data-type=action])`                                    |
| `_secondaryAction`  | `&:is([data-type=secondaryAction])`                           |
| `_info`             | `&:is([data-type=info])`                                      |
| `_success`          | `&:is([data-type=success])`                                   |
| `_warning`          | `&:is([data-type=warning])`                                   |
| `_danger`           | `&:is([data-type=danger], [data-type=error])`                 |

## Customization

Cerberus lets you create your own conditions, so you're not limited to the ones in the default preset.


---
## css-vars

---
title: CSS Variables
description: Using token-aware CSS variables in Cerberus UI
---

## Overview

CSS variables have become the defacto way to create shared values on the web.
It's very useful to avoid prop interpolations, classname regeneration, and
reduce runtime evaluation of token values.

## Examples

### Basic

Use the `css` prop to create css variables

```tsx
<Box css={{ "--font-size": "18px" }}>
  <Text as="h3" css={{ fontSize: "calc(var(--font-size) * 2)" }}>Hello</Text>
  <Text css={{ fontSize: "var(--font-size)" }}>Hello</Text>
</Box>
```

### Access tokens

Use the full token path to access semantic-tokens

```tsx
<Box css={{ "--color": "{colors.danger.text.initial}" }}>
  <Text css={{ color: "var(--color)" }}>Hello</Text>
</Box>
```

Here's an example of how to access size tokens

```tsx
<Box css={{ "--font": "{fonts.display}" }}>
  <Text as="h1" css={{ fontFamily: "var(--font)" }}>Hello</Text>
</Box>
```

### Responsive Styles

Use the responsive syntax to make css variables responsive

```tsx
<Box css={{ "--font-size": { base: "18px", lg: "24px" } }}>
  <Text as="h3" css={{ fontSize: "calc(var(--font-size) * 2)" }}>Hello</Text>
  <Text css={{ fontSize: "var(--font-size)" }}>Hello</Text>
</Box>
```

### Color Opacity Modifier

When accessing color tokens, you can use the opacity modifier to access the
color with an opacity. The requirement is to use the `{}` syntax.

```tsx
<Box css={{ "--color": "{colors.red.500/40}" }}>
  <Text css={{ color: "var(--color)" }}>Hello</Text>
</Box>
```

### Virtual Color

Variables can point to a virtual color via the `colors.colorPalette.*` value.
This is useful for creating theme components.

```jsx
<Box
  colorPalette="success"
  css={{ "--color": "{colors.colorPalette.initial}" }}
>
  <Text css={{ color: "var(--color)" }}>Hello</Text>
</Box>
```


---
## effects

---
title: Effects
description: JSX style props for styling box shadows, opacity, and more
---

## Box Shadow

Use the `shadow` or `boxShadow` prop to apply a box shadow to an element.

```tsx
// hardcoded values
<Box shadow="12px 12px 2px 1px rgba(0, 0, 255, .2)" />

// token values
<Box shadow="lg" />
```

| Prop                   | CSS Property     | Token Category |
| ---------------------- | ---------------- | -------------- |
| `shadows`, `boxShadow` | `box-shadow`     | `shadows`      |
| `shadowColor`          | `--shadow-color` | `colors`       |

## Box Shadow Color

Use the `shadowColor` prop to set the color of a box shadow. This prop maps to
the `--shadow-color` CSS variable.

```tsx
<Box shadow="60px -16px var(--shadow-color)" shadowColor="red" />
```

| Prop          | CSS Property     | Token Category |
| ------------- | ---------------- | -------------- |
| `shadowColor` | `--shadow-color` | `colors`       |

## Opacity

Use the `opacity` prop to set the opacity of an element.

```tsx
<Box opacity="0.5" />
```

| Prop      | CSS Property | Token Category |
| --------- | ------------ | -------------- |
| `opacity` | `opacity`    | `opacity`      |

## Mix Blend Mode

Use the `mixBlendMode` prop to control how an element's content should be
blended with the background.

```tsx
<Box bg="danger.bg.initial">
  <Image src="..." mixBlendMode="hard-light" />
</Box>
```

| Prop           | CSS Property     | Token Category |
| -------------- | ---------------- | -------------- |
| `mixBlendMode` | `mix-blend-mode` | -              |


---
## layer-styles

---
title: Layer Styles
description: Learn how to use layer styles to define visual properties.
---







## Overview

Layer styles allow you to define visual properties. The common properties are:

- Color or text color
- Background color
- Border width and border color
- Box shadow
- Opacity

## Defining layer styles

Layer styles are defined using the `defineLayerStyles` function.


```tsx
// Source available in static configuration: {DEMOS.definingMeta}
```


## Built-in layer styles

Chakra UI provides a set of built-in layer styles.

<DEMOS.basic />

## Updating the theme

To use the layer styles, update the `theme` object with the `layerStyles`
property.


```tsx
// Source available in static configuration: {DEMOS.updating}
```


After updating the theme, run the `typegen` command to generate the typings. See
the [CLI docs](/docs/get-started/cli#chakra-typegen) for how to run typegen in
postinstall, CI, and monorepos.


```bash
npm run prepare
```


## Using layer styles

Now you can use `layerStyle` property in your components.


```tsx
// Source available in static configuration: {DEMOS.usingMeta}
```

<br />

To utilize in the `css` function:


```tsx
// Source available in static configuration: {DEMOS.useFunctionMeta}
```


---
## responsive-design

---
title: Responsive Design
description:
  Learn how to create responsive designs using Cerberus UI's built-in responsive
  style props
---



## Overview

Responsive design is a fundamental aspect of modern web development, allowing
websites and applications to adapt seamlessly to different screen sizes and
devices.

Cerberus provides a comprehensive set of responsive utilities and features to facilitate the creation of responsive layouts. It lets you do this through conditional styles for different breakpoints.

Let's say you want to change the font weight of a text on large screens, you can do it like this:

```tsx
<Text fontWeight="medium" lg={{ fontWeight: 'bold' }}>Text</Text>
```

> **Note:** Cerberus uses a mobile-first breakpoint system and leverages min-width media queries `@media(min-width)` when you write responsive styles.

Cerberus provides five breakpoints by default:

```ts
const breakpoints = {
  sm: '640px',
  md: '768px',
  lg: '1024px',
  xl: '1280px',
  '2xl': '1536px'
}
```

## Object syntax

Cerberus allows you apply the responsive condition directly to a style property, resulting in a more concise syntax:

```diff
<Text
-   fontWeight="medium"
-   lg={{ fontWeight: 'bold' }}
+   fontWeight={{ base: 'medium', lg: 'bold' }}
>
  Text
</Text>
```

### The Array syntax

Cerberus also accepts arrays as values for responsive styles. Pass the corresponding value for each breakpoint in the array. Using our previous code as an example:

```tsx
<Text fontWeight={['medium', undefined, undefined, 'bold']}>
  Text
</Text>
```

> We're leaving the corresponding values of the unused breakpoints `md` and `lg` as undefined.

### Targeting a breakpoint range

By default, styles assigned to a specific breakpoint will be effective at that breakpoint and will persist as applied styles at larger breakpoints.

If you wish to apply a utility exclusively when a particular range of breakpoints is active, Cerberus offers properties that restrict the style to that specific range. To construct the property, combine the minimum and maximum breakpoints using the "To" notation in camelCase format.

Let's say we want to apply styles between the `md` and `xl` breakpoints, we use the `mdToXl` property:

```tsx
<Text fontWeight={{ mdToXl: 'bold' }}>
  Text
</Text>
```

> This text will only be bold in `md`, `lg` and `xl` breakpoints.

### Targeting a single breakpoint

To target a single breakpoint, you can easily achieve this by simply adding the suffix "Only" to the breakpoint name in camelCase format.

Let's say we want to apply styles only in the `lg` breakpoint, we use the `lgOnly` property:

```tsx
<Text fontWeight={{ lgOnly: 'bold' }}>
  Text
</Text>
```

### Customizing Breakpoints

When encountering certain scenarios, it may become necessary to establish custom breakpoints tailored to your application's needs. It is advisable to utilize commonly used aliases such as `sm`, `md`, `lg`, and `xl` for this purpose.

In order to define custom breakpoints, you can easily accomplish this by passing them as an object within your PandaCSS config.

> Note: Make sure that the CSS units of your breakpoints are consistent. Use either all pixels (`px`) or all `em`, but do not mix them.

```js filename="panda.config.ts"
import {
  createCerberusConfig,
  createCerberusPreset,
} from '@cerberus/panda-preset'

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

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

  theme: {
    extend: {
      breakpoints: {
        sm: '640px',
        md: '768px',
        lg: '1024px',
        xl: '1280px',
        '2xl': '1536px'
      }
    }
  }
})
```


---
## spacing

---
title: Spacing
description:
  JSX style props for controlling the padding and margin of an element.
---




## Padding

<NoteAdmonition description={<>See the list of <a href="#reference">built-in spacing values</a> below.</>} />

### All sides

Use the `padding` prop to apply padding on all sides of an element

```tsx
// raw value
<Box padding="40px" />
<Box p="40px" /> // shorthand

// token value
<Box padding="4" />
<Box p="4" /> // shorthand
```

| Prop          | CSS Property | Token Category |
| ------------- | ------------ | -------------- |
| `p`,`padding` | `padding`    | `spacing`      |

### Specific side

Use the `padding{Left,Right,Top,Bottom}` to apply padding on one side of an
element

```tsx
<Box paddingLeft="3" />
<Box pl="3" /> // shorthand

<Box paddingTop="3" />
<Box pt="3" /> // shorthand
```

Use the `padding{Start,End}` props to apply padding on the logical axis of an
element based on the text direction.

```tsx
<Box paddingStart="8" />
<Box ps="8" /> // shorthand

<Box paddingEnd="8" />
<Box pe="8" /> // shorthand
```

> **Note:** PandaCSS will automagically translate pl/r/t/b to use the start/end/block properties for convenience.

| Prop                  | CSS Property           | Token Category |
| --------------------- | ---------------------- | -------------- |
| `pl`, `paddingLeft`   | `padding-left`         | `spacing`      |
| `pr`, `paddingRight`  | `padding-right`        | `spacing`      |
| `pt`, `paddingTop`    | `padding-top`          | `spacing`      |
| `pb`, `paddingBottom` | `padding-bottom`       | `spacing`      |
| `ps`, `paddingStart`  | `padding-inline-start` | `spacing`      |
| `pe`, `paddingEnd`    | `padding-inline-end`   | `spacing`      |

### Horizontal and Vertical padding

Use the `padding{X,Y}` props to apply padding on the horizontal and vertical
axis of an element

```tsx
<Box paddingX="8" />
<Box px="8" /> // shorthand

<Box paddingY="8" />
<Box py="8" /> // shorthand
```

| Prop                  | CSS Property           | Token Category |
| --------------------- | ---------------------- | -------------- |
| `p`,`padding`         | `padding`              | `spacing`      |
| `pl`, `paddingLeft`   | `padding-left`         | `spacing`      |
| `pr`, `paddingRight`  | `padding-right`        | `spacing`      |
| `pt`, `paddingTop`    | `padding-top`          | `spacing`      |
| `pb`, `paddingBottom` | `padding-bottom`       | `spacing`      |
| `px`, `paddingX`      | `padding-inline`       | `spacing`      |
| `py`, `paddingY`      | `padding-block`        | `spacing`      |
| `ps`, `paddingStart`  | `padding-inline-start` | `spacing`      |
| `pe`, `paddingEnd`    | `padding-inline-end`   | `spacing`      |

## Margin

### All sides

Use the `margin` prop to apply margin on all sides of an element

```tsx
<Box margin="5" />
<Box m="5" /> // shorthand
```

| Prop         | CSS Property | Token Category |
| ------------ | ------------ | -------------- |
| `m`,`margin` | `margin`     | `spacing`      |

### Specific side

Use the `margin{Left,Right,Top,Bottom}` to apply margin on one side of an
element

```tsx
<Box marginLeft="3" />
<Box ml="3" /> // shorthand

<Box marginTop="3" />
<Box mt="3" /> // shorthand
```

Use the `margin{Start,End}` properties to apply margin on the logical axis of an
element based on the text direction.

```tsx
<Box marginStart="8" />
<Box ms="8" /> // shorthand

<Box marginEnd="8" />
<Box me="8" /> // shorthand
```

| Prop                 | CSS Property          | Token Category |
| -------------------- | --------------------- | -------------- |
| `ml`, `marginLeft`   | `margin-left`         | `spacing`      |
| `mr`, `marginRight`  | `margin-right`        | `spacing`      |
| `mt`, `marginTop`    | `margin-top`          | `spacing`      |
| `mb`, `marginBottom` | `margin-bottom`       | `spacing`      |
| `ms`, `marginStart`  | `margin-inline-start` | `spacing`      |
| `me`, `marginEnd`    | `margin-inline-end`   | `spacing`      |

### Horizontal and Vertical margin

Use the `margin{X,Y}` properties to apply margin on the horizontal and vertical
axis of an element

```tsx
<Box marginX="8" />
<Box mx="8" /> // shorthand

<Box marginY="8" />
<Box my="8" /> // shorthand
```

| Prop            | CSS Property  | Token Category |
| --------------- | ------------- | -------------- |
| `mx`, `marginX` | `margin-left` | `spacing`      |
| `my`, `marginY` | `margin-top`  | `spacing`      |

## Reference

| Token    | Value | Visual                                                    |
| -------- | ----- | --------------------------------------------------------- |
|  none    |   0   |  <SpacingVisual value="none" />             |
|  xs      |   0.25rem   |  <SpacingVisual value="xs" />                |
|  sm      |   0.5rem   |  <SpacingVisual value="sm" />                  |
|  md      |   1rem   |  <SpacingVisual value="md" />                |
|  lg      |   1.5rem   | <SpacingVisual value="lg" />                     |
|  xl      |   2rem   |  <SpacingVisual value="xl" />                     |
|  2xl     |   3rem   |  <SpacingVisual value="2xl" />                    |
|  3xl     |   4rem   |  <SpacingVisual value="3xl" />                   |
|  full    |   31.25rem | <SpacingVisual value="full" />           |


---
## text-gradient

---
title: Text Gradient
description: JSX style props for applying text gradients using Cerberus tokens
---




## Overview

Text gradients allow you to apply beautiful gradient effects to text content using Cerberus gradient tokens. This is based on the [PandaCSS text gradients documentation](https://panda-css.com/docs/docs/utilities/gradients#text-gradients).

## Using textGradient prop

Use the `textGradient` prop to apply a gradient to text. The gradient tokens follow the pattern `[theme].[mode].[variant]`.

```tsx


function Example() {
  return (
    <Text
      textGradient="to-t"
      gradientFrom="gradient.charon-dark.start"
      gradientTo="gradient.charon-dark.end"
    >
      This text has a gradient effect
    </Text>
  )
}
```

## Using Cerberus Factory

The Cerberus factory provides a convenient way to apply text gradients with inline styles:

```tsx


function Example() {
  return (
    <cerberus.span
      textGradient="to-t"
      gradientFrom="gradient.charon-dark.start"
      gradientTo="gradient.charon-dark.end"
    >
      This is gradient text using the factory
    </cerberus.span>
  )
}
```

## Live Examples

Here are some examples of text gradients in action:

}>
```tsx title="Text gradient examples"



export default function TextGradientPreview() {
  return (
    <cerberus.div display="flex" flexDirection="column" gap="4" padding="6">
      <cerberus.h3
        textStyle="h3"
        textGradient="to-b"
        gradientFrom="gradient.charon-dark.start"
        gradientTo="gradient.charon-dark.end"
      >
        Charon Dark Gradient
      </cerberus.h3>

      <p
        className={css({
          textStyle: 'body-lg',
          textGradient: 'to-b',
          gradientFrom: 'gradient.charon-light.start',
          gradientTo: 'gradient.charon-light.end',
        })}
      >
        This text uses the Charon light gradient variant.
      </p>

      <p
        className={css({
          textStyle: 'heading-md',
          textGradient: 'to-b',
          gradientFrom: 'gradient.nyx-dark.start',
          gradientTo: 'gradient.nyx-dark.end',
        })}
      >
        Nyx dark gradient creates a striking effect.
      </p>

      <p
        className={css({
          textStyle: 'body-lg',
          textGradient: 'to-b',
          gradientFrom: 'gradient.amphiaraus-light.start',
          gradientTo: 'gradient.amphiaraus-light.end',
        })}
      >
        Amphiaraus light gradient for subtle elegance.
      </p>
    </cerberus.div>
  )
}
```


## Available Gradient Tokens

Cerberus provides several gradient variants, each available in light and dark modes:

[View the cerberus gradients](/docs/theming/gradients)

## Advanced

For theme-aware gradients, you can use conditional styles directly on the cerberus factory:

```tsx


function Example() {
  return (
    <cerberus.span
      display="block"
      _cerberusTheme={{
        textGradient="to-b"
        gradientFrom="gradient.charon-dark.start"
        gradientTo="gradient.charon-dark.end"
      }}
      _acheronTheme={{
        textGradient="to-t"
        gradientFrom="gradient.charon-light.start"
        gradientTo="gradient.charon-light.end"
      }}
    >
      Theme-aware gradient text
    </cerberus.span>
  )
}
```

## Style Props Reference

| Prop           | CSS Property                           | Token Category |
| -------------- | -------------------------------------- | -------------- |
| `textGradient` | `background-image`, `background-clip`  | `gradients`    |

## Implementation Notes

- Text gradients use `background-image` with `background-clip: text` to achieve the effect
- The text becomes transparent and the background gradient shows through
- Works best with bold or medium font weights for better visibility
- Supports theme-aware gradients that adapt to light/dark modes


---
## text-styles

---
title: Text Styles
description:
  Learn how to use text styles to define typography related properties.
---



## Overview

Text styles allows you to define textual css properties. The common properties
are:

- **Font**: font family, weight, size
- **Line height**
- **Letter spacing**
- **Text decoration**
- **Text transform**

## Defining text styles

Text styles are defined using the `defineTextStyles` function.

```ts title="text-styles.ts"


export const textStyles = defineTextStyles({
  body: {
    description: "The body text style - used in paragraphs",
    value: {
      fontFamily: "Inter",
      fontWeight: "500",
      fontSize: "16px",
      lineHeight: "24",
      letterSpacing: "0",
      textDecoration: "None",
      textTransform: "None",
    },
  },
})
```

## Built-in text styles

Cerberus provides a set of built-in text styles.

<TypographyList />

## Update the theme

To use the text styles, update the `theme` object with the `textStyles`
property.

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


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

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

  theme: {
    extend: {
      textStyles,
    },
  }
})
```

## Using text styles

Now you can use `textStyle` property in your components.

```jsx
<Box textStyle="body">This is the body text style</Box>
```


---
## theme-mode

---
title: Themes & Color Modes
description: Learn how to implement themes and color modes in Cerberus Design System
---



## Overview

Cerberus provides support for themes and color modes, allowing you to create visually appealing and accessible applications that adapt to user preferences.

## Themes

To use a theme, just add the `data-panda-theme` attribute to your root `html` tag.

```tsx
<html lang="en" data-panda-theme="cerberus">
  <body>{children}</body>
</html>
```

Cerberus comes with two built-in themes: `cerberus` and `acheron`. You can switch between these themes by changing the value of the `data-panda-theme` attribute.

## Color Modes

Cerberus supports two color modes: `light` and `dark`. You can set the default color mode by adding the `data-color-mode` attribute to your root `html` tag.

```tsx
<html lang="en" data-panda-theme="cerberus" data-color-mode="light">
  <body>{children}</body>
</html>
```

Color mode works the same way as themes. You can switch between light and dark modes by changing the value of the `data-color-mode` attribute.

## Nesting themes and color modes

You can also nest themes and color modes within your application using the [`Theme` component](/docs/components/theme). This is useful when you want to apply a different theme or color mode to a specific section of your app.

```tsx
<html lang="en" data-panda-theme="cerberus" data-color-mode="light">
  <body>
    <Text>This text is in the Cerberus theme and light mode</Text>

    <Theme theme="acheron" mode="dark">
      <Text>This text is in the Acheron theme and dark mode</Text>
    </Theme>
  </body>
</html>
```

## Custom Themes and Color Modes

You can create your own themes and modes by extending your `panda.config.ts` file. For more information, check out the [Multi-Theme Support](https://panda-css.com/docs/guides/multiple-themes) sections in the PandaCSS documentation.

> **Note:** Cerberus will provide a way to streamline this via the `createCerberusPreset` in a future release.


---
## transitions

---
title: Transitions
description:
  JSX style props for controlling an element's transition and animation.
---



## Transition

Use the `transition` prop to control the transition of an element.

```tsx
// hardcoded value
<Box
  bg="danger.bg.initial"
  transition="background 0.2s ease-in-out"
  _hover={{
    bg: "danger.bg.hover"
  }}
>
  Hover me
</Box>

// shortcut value
<Box bg="danger.bg.initial" _hover={{ bg: "danger.bg.hover" }} transition="backgrounds">
  Hover me
</Box>
```

| Prop         | CSS Property | Token Category |
| ------------ | ------------ | -------------- |
| `transition` | `transition` | -              |

## Transition Timing Function

Use the `transitionTimingFunction` prop to control the timing function of a
transition.

```tsx
<Box
  bg="danger.bg.initial"
  _hover={{ bg: "danger.bg.hover" }}
  transition="backgrounds"
  transitionTimingFunction="ease-in-out"
>
  Hover me
</Box>
```

| Prop                       | CSS Property                 | Token Category |
| -------------------------- | ---------------------------- | -------------- |
| `transitionTimingFunction` | `transition-timing-function` | `easings`      |

## Transition Duration

Use the `transitionDuration` prop to control the duration of a transition.

```tsx
<Box
  bg="danger.bg.initial"
  _hover={{ bg: "danger.bg.hover" }}
  transition="backgrounds"
  transitionDuration="fast"
>
  Hover me
</Box>
```

| Prop                 | CSS Property          | Token Category |
| -------------------- | --------------------- | -------------- |
| `transitionDuration` | `transition-duration` | `durations`    |

## Transition Delay

Use the `transitionDelay` prop to control the delay of a transition.

```tsx
<Box
  bg="danger.bg.initial"
  _hover={{ bg: "danger.bg.hover" }}
  transition="backgrounds"
  transitionDelay="fast"
>
  Hover me
</Box>
```

| Prop              | CSS Property       | Token Category |
| ----------------- | ------------------ | -------------- |
| `transitionDelay` | `transition-delay` | `durations`    |

## Animation

Use the `animation` prop to control the animation of an element.

```tsx
<Box animation="bounce" />
```

| Prop        | CSS Property     | Token Category |
| ----------- | ---------------- | -------------- |
| `animation` | `animation-name	` | `animations`   |

## Animation Name

Use the `animationName` prop to control the name of an animation. Compose
multiple animation names to create complex animations.

> **Note:** The value of the `animation` prop points to a global keyframe animation. Use the `theme.keyframes` object to define the animation.

```tsx
<Box animationName="bounce, fade-in" animationDuration="fast" />
```

| Prop            | CSS Property     | Token Category |
| --------------- | ---------------- | -------------- |
| `animationName` | `animation-name` | `animations`   |

## Animation Timing Function

Use the `animationTimingFunction` prop to control the timing function of an
animation.

```tsx
<Box animation="bounce" animationTimingFunction="ease-in-out" />
```

| Prop                      | CSS Property                | Token Category |
| ------------------------- | --------------------------- | -------------- |
| `animationTimingFunction` | `animation-timing-function` | `easings`      |

## Animation Duration

Use the `animationDuration` prop to control the duration of an animation.

```tsx
<Box animation="bounce" animationDuration="fast" />
```

| Prop                | CSS Property         | Token Category |
| ------------------- | -------------------- | -------------- |
| `animationDuration` | `animation-duration` | `durations`    |

## Animation Delay

Use the `animationDelay` prop to control the delay of an animation.

```tsx
<Box animation="bounce" animationDelay="fast" />
```

| Prop             | CSS Property      | Token Category |
| ---------------- | ----------------- | -------------- |
| `animationDelay` | `animation-delay` | `durations`    |


---
## virtual-color

---
title: Virtual Color
description: Create color placeholders for better theming and customization.
---



## Overview

Cerberus allows you to create a virtual color or color placeholder in your
project. The `colorPalette` property is how you create virtual color.

```tsx
<Box
  colorPalette="action"
  bgColor={{
    base: "colorPalette.bg.initial",
    _hover: "colorPalette.bg.hover"
  }}
>
  Hello World
</Box>
```

This will translate to the `action.bg.initial` background color and `action.bg.hover` background color on hover.

## Usage

The fundamental requirement for virtual colors is that your colors must have a
consistent naming convention. By default, Cerberus uses our Semantic Palettes for each color we provide which corresponds to how it should be used in your application.

This makes it easier for you to create and use virtual colors based on theming. Let's say we need to create a themable outline button from scratch.

```tsx
<Button
  css={{
    colorPalette: 'action',
    borderWidth: '1px',
    borderColor: 'colorPalette.border.initial',
    color: 'colorPalette.text.initial',
    _hover: {
      borderColor: 'colorPalette.border.100',
    }
    _focus: {
      borderColor: 'colorPalette.border.focus',
    }
  }}
>
  Click me
</Button>
```

### Recipes

Virtual colors are most useful when used with recipes.

```typescript
const buttonRecipe = defineRecipe({
  base: {
    alignItems: "center",
    bg: "colorPalette.bg.initial",
    color: "colorPalette.text.initial",
    display: "flex",
    justifyContent: "center",
    _hover: {
      bg: "colorPalette.bg.hover",
    },
  },
  variants: {
    palette: {
      action: {
        colorPalette: "action",
      },
      secondary: {
        colorPalette: "secondaryAction",
      },
    },
  },
})
```

### Components

Most built-in components in Cerberus support virtual colors via the `palette` prop. To override the `palette` with a custom palette in your theme, use the `css` prop to define the virtual color.

> **Note:** For virtual colors to work with Cerberus components, ensure your custom palette matches the naming convention used in the original palette you want to mirror.

```tsx
<Button
  css={{
    colorPalette: 'myCustomActionPalette',
  }}
>
  Click me
</Button>
```

### Dark mode

Another amazing thing you can do with virtual colors is to use them with dark
mode.

```tsx
<Box
  colorPalette="page"
  bg={{
     base: "colorPalette.surface.initial",
     _dark: "colorPalette.surface.inverse"
 }}
>
  Hello World
</Box>
```

> This element will have a `page.surface.initial` background color in light mode and a `page.surface.inverse` background color in dark mode.


---
## z-index

---
title: z-index
description: The z-index property controls the vertical stacking order of elements that overlap.
---




## Overview

Use the `zIndex` to apply layering to an element.

```tsx
<Box zIndex="sticky" />
```

| Prop                   | CSS Property     | Token Category |
| ---------------------- | ---------------- | -------------- |
| `zIndex`               | `z-index`        | `zIndex `      |

## Layer Playground

<ZPreview />

## Values

<ZList />


---
## animations

---
title: Animations
description: A list of animations available in Cerberus.
---




## Keyframes

Cerberus provides a set of keyframes out of the box for common animations.

`theme.tokens.keyframes`

<Keyframes />

## Durations

Cerberus provides a set of durations out of the box for common animations.

`theme.tokens.durations`

<Durations />


---
## colors

---
title: Colors
description: A list of colors available in Cerberus.
---




## Primitives

Cerberus provides a comprehensive set of **primitive colors** (`theme.tokens.colors`) that serve as the foundation for all semantic tokens. These are the raw color values that semantic tokens reference.

<PrimitiveColorGroup />

Primitive colors are organized by color families and include numerical scales (e.g., `neutral.0` to `neutral.100`) that provide fine-grained control over color variations. These colors form the building blocks that semantic tokens reference to create meaningful, contextual color usage.

**How Primitives Relate to Semantic Tokens:**
- Semantic tokens like `page.bg.initial` reference primitive colors using token syntax: `{colors.cerberus.neutral.5}`
- This creates a clear hierarchy: primitives → semantic tokens → component usage
- Customizing primitive colors automatically updates all semantic tokens that reference them

## Semantic Tokens

Cerberus provides a set of semantic colors that drive our themes.

### Page

Used for pages, layouts, and any other container that is relative to a page.

<PaletteGroup palette="page" />

### Action

The primary palette for actions, such as buttons, links, and other interactive elements.

<PaletteGroup palette="action" />

### Secondary Action

The secondary palette for actions, such as buttons, links, and other interactive elements.

<PaletteGroup palette="secondaryAction" />

### Info

Used for informational elements, such as badges, tags, and other non-interactive elements.

<PaletteGroup palette="info" />

### Success

Used for success states, such as success messages, notifications, and other positive feedback.

<PaletteGroup palette="success" />

### Warning

Used for warning states, such as warning messages, notifications, and other cautionary feedback.

<PaletteGroup palette="warning" />

### Danger

Used for danger states, such as error messages, notifications, and other negative feedback.

<PaletteGroup palette="danger" />

### Data-Visualization

Used for data visualization elements, such as charts, graphs, and other visual representations of data.

<PaletteGroup palette="dataViz" />

## Naming Convention

Cerberus uses a consistent naming convention for colors to ensure clarity and maintainability. Each color is named based on its purpose and context, making it easier to understand its intended use.

```bash
[palette?].[usage].[prominence?].[interaction?]
```

| Name        | Description                                                    |
| ----------- | -------------------------------------------------------------- |
| Palette     | The category/context of where the color is used.               |
| Usage       | How the color is used within the context.                      |
| Prominence  | The hierarchy of the color used within the page context.       |
| Interaction | The element interaction type the color should be applied to.   |


---
## gradients

---
title: Gradients
description: Gradients in the design system.
---



## Tokens

Cerberus provides the following gradient tokens:

`theme.tokens.gradients`

<GradientList />


---
## overview

---
title: Overview
description: A guide for configuring the Cerberus theming system.
---

## Architecture

The Cerberus theming system is built around the API of
[Panda CSS](https://panda-css.com/).

Here's a quick overview of how the system is structured to provide a performant
and extensible styling system:

- Define the styling system configuration using the `createCerberusConfig` function
- Create the styling engine using the `makeSystemConfig` function
- Pass the styling engine to the `CerberusProvider` component

```tsx title="cerberus-config.client.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'


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>
}
```

## Config

The Cerberus system is configured using the `createCerberusConfig` function. This function accepts a configuration object that allows you to customize the styling system's behavior.

After a config is defined, the `makeSystemConfig` function creates internal options for Cerberus components to utilize when needed.

### cssVarRoot

`cssVarRoot` is the root element where the token CSS variables will be applied.

```tsx title="panda.config.ts"
export default createCerberusConfig({
  cssVarRoot: ":where(:root, :host)",
})
```

### globalCss

`globalCss` is used to apply global styles to the system. This will not be atomized, and will be applied to the root element.

```tsx title="panda.config.ts"
export default createCerberusConfig({
  globalCss: {
    "html, body": {
      margin: 0,
      padding: 0,
    },
  },
})
```

### preflight

`preflight` is used to apply css reset styles to the system.

```tsx title="panda.config.ts"
export default createCerberusConfig({
  preflight: false,
})
```

Alternatively, you can use the `preflight` config property to apply css reset
styles to the system. This is useful if you want to apply css reset styles to a
specific element.

```tsx title="panda.config.ts"
export default createCerberusConfig({
  preflight: {
    scope: ".custom-reset",
  },
})
```

### theme

Use the `theme` config property to define the system theme. This property
accepts the following properties:

- `breakpoints`: for defining breakpoints
- `keyframes`: for defining css keyframes animations
- `tokens`: for defining primitive tokens
- `semanticTokens`: for defining semantic tokens (which consume primitive tokens)
- `textStyles`: for defining typography styles
- `layerStyles`: for defining layer styles
- `animationStyles`: for defining animation styles
- `recipes`: for defining component recipes
- `slotRecipes`: for defining component slot recipes

```tsx title="panda.config.ts"
export default createCerberusConfig({
  theme: {
    breakpoints: {
      sm: "320px",
      md: "768px",
      lg: "960px",
      xl: "1200px",
    },
    tokens: {
      colors: {
        red: "#EE0F0F",
      },
    },
    semanticTokens: {
      colors: {
        customRed: { value: "{colors.red}" },
      },
    },
    keyframes: {
      spin: {
        from: { transform: "rotate(0deg)" },
        to: { transform: "rotate(360deg)" },
      },
    },
  },
})
```

### conditions

Use the `conditions` config property to define custom selectors and media query
conditions for applying conditional styles in the system.

```tsx title="panda.config.ts"
export default createCerberusConfig({
  conditions: {
    cqSm: "@container(min-width: 320px)",
    child: "& > *",
  },
})
```

Sample usage:

```tsx
<Box mt="40px" _cqSm={{ mt: "0px" }}>
  <Text>Hello World</Text>
</Box>
```

### strictTokens

Use the `strictTokens` config property to enforce the usage of only design
tokens. This will throw a TS error if you try to use a token that is not defined
in the theme.

```tsx title="panda.config.ts"
export default createCerberusConfig({
  strictTokens: true,
})

```

```tsx
// ❌ This will throw a TS error
<Box color="#4f343e">Hello World</Box>

// ✅ This will work
<Box color="red.400">Hello World</Box>
```

## TypeScript

When you configure the system properties (like `colors`, `space`, `fonts`,
etc.), the Panda CLI can be used to generate type definitions for them.

```bash
npm panda codegen
```

This will update the internal types in the `styled-system` directory, and make
sure they are in sync with the theme. Providing a type-safe API and delightful
experience for developers.

## System

After a config is defined, it is passed to the `makeSystemConfig` function to create low level options that become internally available to components.

```ts
const icons = defineIcons({...})
const config = makeSystemConfig({
  icons,
})
```

The system includes the following properties:

### icons

The token function is used to create a mapping of icon names to their respective
icon components. This allows you to easily reference and use custom icons throughout your application for the Cerberus components that depend on rendering icons for their functionality.

```tsx title="panda.config.ts"



const icons = defineIcons({
  calendar: Calendar,
  checkmark: Checkmark,
})
```

## Tokens

To learn more about tokens, please refer to the [tokens](/docs/theming/tokens)
section.

## Recipes

To learn more about recipes, please refer to the
[recipes](/docs/theming/recipes) section.


---
## recipes

---
title: Recipes
description: Writing multi-variant styles with recipes in Cerberus.
---

## Overview

Cerberus provides a way to write CSS-in-JS with better performance, developer
experience, and composability. One of its key features is the ability to create
multi-variant styles with a type-safe runtime API.

A recipe consists of these properties:

- `className`: The className to attach to the component
- `base`: The base styles for the component
- `variants`: The different visual styles for the component
- `compoundVariants`: The different combinations of variants for the component
- `defaultVariants`: The default variant values for the component

## Defining the recipe

Use the `defineRecipe` identity function to create a recipe.

```tsx title="button.recipe.ts"


export const buttonRecipe = defineRecipe({
  base: {
    display: "flex",
  },
  variants: {
    visual: {
      solid: { bg: "red.200", color: "white" },
      outline: { borderWidth: "1px", borderColor: "red.200" },
    },
    size: {
      sm: { padding: "4", fontSize: "12px" },
      lg: { padding: "8", fontSize: "24px" },
    },
  },
})
```

Then add it to your theme:

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

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

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

  theme: {
    extend: {
      recipes: {
        myButton: buttonRecipe,
      },
    },
  }
})
```

## Using the recipe

After defining recipes, we recommend using the Panda CLI to generate
theme typings for your recipe.

```bash
npm panda codegen
```

There are two ways to use the recipe in a component:

- Directly in the component
- Creating a component (recommended) with the `Cerberus` factory

### With the Cerberus Factory

Import the `button` recipe from your local `styled-system/recipes` folder and use it within your component.

```tsx title="button.tsx"



const { withRecipe } = createCerberusPrimitive<ButtonVariantProps>(buttonRecipe)

function MyCustomButton(props: ButtonVariantProps) {
  const dynamicValue = props.something ? 'yes' : 'no'
  return <button data-dynamic-thing={dynamicValue} {...props}>Click Me</button>
}

export const Button = withRecipe(MyCustomButton)
```

### Directly in the Component

#### splitVariantProps

You can also use the `[recipe].splitVariantProps` function to split the recipe
props from the component props. This is useful if you are not using the factory to create components.

```tsx title="button.tsx" {11}
'use client';




interface CustomButtonProps extends ButtonVariantProps {
  doSomething: () => void
}

export function MyCustomButton(props: CerberusPrimitiveProps<CustomButtonProps>) {
  const [recipeProps, restProps] = buttonRecipe.splitVariantProps(props)
  const styles = buttonRecipe(recipeProps)
  return(
    <cerberus.button
      {...restProps}
      className={styles}
      onClick={restProps.doSomething}
    >
      Click Me
    </cerberus.button>
  )
}
```

#### TypeScript

To infer the recipe variant prop types, use the `*VariantProps` type.

```tsx title="button.tsx"


export interface ButtonProps extends ButtonVariantProps {}
```

## Default Variants

The `defaultVariants` property is used to set the default variant values for the
recipe. This is useful when you want to apply a variant by default.

```tsx title="button.recipe.ts" {17-20}


export const buttonRecipe = defineRecipe({
  base: {
    display: "flex",
  },
  variants: {
    visual: {
      solid: { bg: "red.200", color: "white" },
      outline: { borderWidth: "1px", borderColor: "red.200" },
    },
    size: {
      sm: { padding: "4", fontSize: "12px" },
      lg: { padding: "8", fontSize: "24px" },
    },
  },
  defaultVariants: {
    visual: "solid",
    size: "sm",
  },
})
```

## Compound Variants

Use the `compoundVariants` property to define a set of variants that are applied
based on a combination of other variants.

```tsx title="button.recipe.ts"


export const buttonRecipe = defineRecipe({
  base: {
    display: "flex",
  },
  variants: {
    visual: {
      solid: { bg: "red.200", color: "white" },
      outline: { borderWidth: "1px", borderColor: "red.200" },
    },
    size: {
      sm: { padding: "4", fontSize: "12px" },
      lg: { padding: "8", fontSize: "24px" },
    },
  },
  compoundVariants: [
    {
      size: "small",
      visual: "outline",
      css: {
        borderColor: "blue.500",
      },
    },
  ]
})
```

When you use the `size="small"` and `visual="outline"` variants together, the
`compoundVariants` will apply the `css` property to the component.

```tsx title="app.tsx"
<Button size="small" visual="outline">
  Click Me
</Button>
```

### Caveat

Due to the design constraints, using `compoundVariants` with responsive values
doesn't work.

This means a code like this will not work:

```tsx
<Button size={{ base: "sm", md: "lg" }} visual="outline">
  Click Me
</Button>
```

For this cases, we recommend rendering multiple versions of the component with
different breakpoints, then hide/show as needed.


---
## semantic-tokens

---
title: Semantic Tokens
description: Leveraging semantic tokens for design decisions in your app.
---



## Overview

Semantic tokens are tokens that are designed to be used in a specific context. A
semantic token consists of the following properties:

- `value`: The value of the token or a reference to an existing token.
- `description`: An optional description of what the token can be used for.

## Defining Semantic Tokens

In most cases, the value of a semantic token should reference to an existing (primitive) token.

> To reference a value in a semantic token, use the token reference `{}` syntax.

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

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

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

  theme: {
    tokens: {
      colors: {
        red: { value: "#EE0F0F" },
      },
    },
    semanticTokens: {
      colors: {
        invalid: { value: "{colors.red}" },
      },
    },
  },
})
```

## Using Semantic Tokens

After defining semantic tokens, we recommend using the Panda CLI to generate
theme typings for your tokens.

```bash
npm panda codegen
```

This will provide autocompletion for your tokens in your editor.

```tsx
<Box color="invalid">Hello World</Box>
```

## Conditional Token

Semantic tokens can also be changed based on the conditions like light and dark
modes.

For example, if you want a color to change automatically based on light or dark
mode.

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

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

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

  theme: {
    tokens: {
      danger: {
          red: { value: "red.500" },
          darkRed: { value: "red.600" },
          green: { value: "green.500" },
          darkGreen: { value: "green.600" },
        },
    },
    semanticTokens: {
      colors: {
        danger: {
          value: { base: "{colors.red}", _dark: "{colors.darkRed}" },
        },
        success: {
          value: { base: "{colors.green}",  _dark: "{colors.darkGreen}" },
        },
      },
    },
  },
})
```

> The conditions used in semantic tokens must be an at-rule or parent selector [condition](/docs/styling/conditional-styles#reference).

## Semantic Token Nesting

Semantic tokens can be nested to create a hierarchy of tokens. This is useful
when you want to group tokens together.

> Use the `DEFAULT` key to define the default value of a nested token.

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

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

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

  theme: {
    semanticTokens: {
      colors: {
        bg: {
          DEFAULT: { value: "{colors.gray.100}" },
          primary: { value: "{colors.teal.100}" },
          secondary: { value: "{colors.gray.100}" },
        },
      },
    },
  },
})
```

This allows the use of the `bg` token in the following ways:

```tsx
<Box bg="bg">
  <Box bg="bg.primary">Hello World</Box>
  <Box bg="bg.secondary">Hello World</Box>
</Box>
```


---
## shadows

---
title: Shadows
description: Shadow design tokens available in the Cerberus Design System.
---



## Overview

Shadow tokens represent the shadow of an element. They provide depth and hierarchy to your interface by creating visual layers. Cerberus provides a set of predefined shadow tokens that you can use throughout your application.

## Tokens

Cerberus provides the following shadow tokens:

`theme.tokens.shadows`

<ShadowTokens />

## Usage

You can use shadow tokens with the `shadow` or `boxShadow` props:

```tsx


// Using predefined shadow tokens
<Box shadow="sm">Small shadow</Box>
<Box shadow="md">Medium shadow</Box>
<Box shadow="lg">Large shadow</Box>

// Using boxShadow prop
<Box boxShadow="md">Medium shadow</Box>
```

## Custom Shadows

You can also define custom shadow tokens in your theme configuration:

```tsx title="panda.config.ts"
import {
  createCerberusConfig,
  createCerberusPreset,
} from '@cerberus/panda-preset'

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

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

  theme: {
    extend: {
      tokens: {
        shadows: {
          custom: {
            value: "0 4px 8px rgba(0, 0, 0, 0.1)"
          },
          glow: {
            value: "0 0 20px rgba(59, 130, 246, 0.5)"
          }
        }
      }
    }
  }
})
```

## Shadow Values

The shadow tokens support both string values and composite objects:

### String Values

```tsx
shadows: {
  simple: { value: "0 1px 3px rgba(0, 0, 0, 0.1)" }
}
```

### Composite Values

```tsx
shadows: {
  complex: {
    value: {
      offsetX: 0,
      offsetY: 4,
      blur: 8,
      spread: 0,
      color: "rgba(0, 0, 0, 0.1)"
    }
  }
}
```

### Multiple Shadows

```tsx
shadows: {
  layered: {
    value: [
      "0 1px 2px rgba(0, 0, 0, 0.05)",
      "0 4px 8px rgba(0, 0, 0, 0.1)"
    ]
  }
}
```


---
## slot-recipes

---
title: Slot Recipes
description: Learn how to style multiple parts components with slot recipes.
---

## Overview

Slot Recipes come in handy when you need to apply style variations to multiple
parts of a component.

A slot recipe consists of these properties:

- `className`: The className prefix to attach to the component slot
- `slots`: An array of component parts to style
- `jsx`: An optional array of elements that will consume the recipe
- `base`: The base styles per slot
- `variants`: The different visual styles for each slot
- `defaultVariants`: The default variant for the component
- `compoundVariants`: The compound variant combination and style overrides for
  each slot.

Slot recipes use the same syntax as PandaCSS recipes, but they are specifically
designed to style multiple parts of a component.

## Defining the recipe

Use the `defineSlotRecipe` identity function to create a slot recipe.

```tsx title="checkbox.recipe.ts"


export const checkboxSlotRecipe = defineSlotRecipe({
  className: "checkbox",
  slots: ["root", "control", "label"],
  base: {
    root: { display: "flex", alignItems: "center", gap: "2" },
    control: { borderWidth: "1px", borderRadius: "sm" },
    label: { marginStart: "2" },
  },
  variants: {
    size: {
      sm: {
        control: { width: "8", height: "8" },
        label: { fontSize: "sm" },
      },
      md: {
        control: { width: "10", height: "10" },
        label: { fontSize: "md" },
      },
    },
  },
})
```

## Using the recipe

After defining recipes, we recommend using the Panda CLI to generate
theme typings for your recipe.

```bash
npm panda codegen
```

There are two ways to use the recipe in a component:

- Directly in the component
- Creating a component (recommended) with the `Cerberus` factory

### With the Cerberus Factory

Import the `checkbox` recipe from your local `styled-system/recipes` folder and use it within your component.

```tsx title="checkbox.tsx"



const { withSlotRecipe } = createCerberusPrimitive<CheckboxVariantProps>(checkboxRecipe)

export const CheckboxRoot = withSlotRecipe(cerberus.div, "root")
export const CheckboxControl = withSlotRecipe(cerberus.input, "control")
export const CheckboxLabel = withSlotRecipe(cerberus.label, "label")
```

### Directly in the Component

#### splitVariantProps

You can also use the `[recipe].splitVariantProps` function to split the recipe
props from the component props. This is useful if you are not using the factory to create components.

```tsx title="checkbox.tsx" {10}
'use client';



interface CustomCheckboxControlProps extends CheckboxVariantProps {
  onChange: () => void
}

export function MyCustomCheckboxControl(props: CustomCheckboxControlProps) {
  const [recipeProps, restProps] = checkboxRecipe.splitVariantProps(props)
  const styles = checkboxRecipe(recipeProps)
  return(
    <div className={styles.root}>
      <label className={styles.label}>{restProps.label}</label>
      <input
        className={styles.control}
        onChange={restProps.onChange}
      />
    </div>
  )
}
```

#### TypeScript

To infer the recipe variant prop types, use the `*VariantProps` type.

```tsx title="checkbox.tsx"


export interface CheckboxRootProps extends CheckboxVariantProps {}
```

## Compound Variants

Use the `compoundVariants` property to define a set of variants that are applied
based on a combination of other variants.

```tsx title="checkbox.recipe.ts" /compoundVariants/


export const checkboxRecipe = defineSlotRecipe({
  slots: ["root", "control", "label"],
  base: {},
  variants: {
    size: {
      sm: {},
      md: {},
    },
    visual: {
      contained: {},
      outline: {},
    },
  },
  compoundVariants: [
    {
      size: "sm",
      visual: "outline",
      css: {
        control: { borderWidth: "1px" },
        label: { color: "green.500" },
      },
    },
  ],
})
```

## Targeting a slot

In some cases, targeting a slot by className might be needed.

- Set the `className` property in the config
- The naming convention is `${className}__${slot}`

```tsx title="checkbox.recipe.ts" /& .checkbox__label/


export const checkboxRecipe = defineSlotRecipe({
  className: "checkbox",
  slots: ["root", "control", "label"],
  base: {
    root: {
      bg: "blue.500",
      _hover: {
        "& .checkbox__label": { color: "white" },
      },
    },
  },
})
```

### TypeScript

Use the PandaCSS CLI to generate the types for the recipe.

```bash
npm panda codegen
```

This will register the recipe and generate the types for the slots.


---
## spacing

---
title: Spacing
description: Spacing utilities in the design system.
---



## Tokens

Cerberus provides the following spacing tokens:

`theme.tokens.spacing`

| Token    | Value | Visual                                                    |
| -------- | ----- | --------------------------------------------------------- |
|  none    |   0   |  <SpacingVisual value="none" />                           |
|  xs      |   0.25rem   |  <SpacingVisual value="xs" />                       |
|  sm      |   0.5rem   |  <SpacingVisual value="sm" />                        |
|  md      |   1rem   |  <SpacingVisual value="md" />                          |
|  lg      |   1.5rem   | <SpacingVisual value="lg" />                         |
|  xl      |   2rem   |  <SpacingVisual value="xl" />                          |
|  2xl     |   3rem   |  <SpacingVisual value="2xl" />                         |
|  3xl     |   4rem   |  <SpacingVisual value="3xl" />                         |
|  full    |   31.25rem | <SpacingVisual value="full" />                       |


---
## tokens

---
title: Tokens
description: Managing design decisions in your app using tokens.
---



## Overview

Design tokens are the platform-agnostic way to manage design decisions in your
application or website. It is a collection of attributes that describe any
fundamental/atomic visual style. Each attribute is a key-value pair.

> Design tokens in Cerberus are largely influenced by the
> [W3C Token Format](https://tr.designtokens.org/format/).

A design token consists of the following properties:

- `value`: The value of the token. This can be any valid CSS value.
- `description`: An optional description of what the token can be used for.

## Defining Tokens

Tokens are defined in the under the `theme` key in your system config.


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

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

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

  theme: {
    tokens: {
      colors: {
        primary: { value: "#0FEE0F" },
        secondary: { value: "#EE0F0F" },
      },
      fonts: {
        body: { value: "system-ui, sans-serif" },
      },
      shadows: {
        custom: { value: "0 4px 8px rgba(0, 0, 0, 0.1)" },
      },
    },
  },
})
```

> **Note:** Token values need to be nested in an object with a `value` key. This is to allow for additional properties like `description` and more in the future.

## Using Tokens

After defining tokens, we recommend using the Panda CLI to generate theme
typings for your tokens.

```bash
npm panda codegen
```

This will provide autocompletion for your tokens in your editor.

```tsx
<Box color="primary" fontFamily="body">
  Hello World
</Box>
```

### Token reference syntax

Cerberus enables you to reference design tokens within composite values for CSS
properties like `border`, `padding`, and `box-shadow`.
This is achieved through the token reference syntax: `{path.to.token}`.

> **Note:** It is important to use the complete token path; for example, instead of using
`red.300`, you must reference it as `colors.red.300`.


Here’s an example where token reference syntax is applied to both the border and
p (padding) props:

```tsx
<Box
  border="1px solid {colors.red.300}"
  p="{spacing.4} {spacing.6} {spacing.8} {spacing.10}"
  boxShadow="{spacing.4} {spacing.2} {spacing.2} {colors.red.300}"
/>
```

## Token Nesting

Tokens can be nested to create a hierarchy of tokens. This is useful when you
want to group related tokens together.

> **Note:** Use the `DEFAULT` key to define the default value of a nested token.

```ts title="panda.config.ts"
export default createCerberusConfig({
  presets: [createCerberusPreset()],

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

  theme: {
    tokens: {
      colors: {
        red: {
          DEFAULT: { value: "#EE0F0F" },
          100: { value: "#EE0F0F" },
        },
      },
      fonts: {
        body: { value: "system-ui, sans-serif" },
      },
    },
  },
})
```

```tsx
<Box
  // 👇🏻 This will use the `DEFAULT` value
  bg="red"
  color="red.100"
>
  Hello World
</Box>
```

## Token Types

### Colors

Colors have meaning and support the purpose of the content, communicating things
like hierarchy of information, and states. It is mostly defined as a string
value or reference to other tokens.

```tsx title="theme.ts"


export export const tokens = defineTokens({
  colors: {
    red: {
      100: { value: "#fff1f0" },
    },
  },
})
```

### Gradients

Gradient tokens represent a smooth transition between two or more colors. Its
value can be defined as a string or a composite value.

```tsx title="theme.ts"


export export const tokens = defineTokens({
  gradients: {
    // string value
    simple: { value: "linear-gradient(to right, red, blue)" },

    // composite value
    primary: {
      value: { type: "linear", placement: "to right", stops: ["red", "blue"] },
    },
  },
})
```

### Sizes

Size tokens represent the width and height of an element. Its value is defined
as a string.

```tsx title="theme.ts"


export export const tokens = defineTokens({
  sizes: {
    sm: { value: "12px" },
  },
})
```

> Size tokens are typically used in `width`, `height`, `minWidth`, `maxWidth`,
> `minHeight`, `maxHeight` properties.

### Spacing

Spacing tokens represent the margin and padding of an element. Its value is
defined as a string.

```tsx title="theme.ts"


export export const tokens = defineTokens({
  spacing: {
    gutter: { value: "12px" },
  },
})
```

> Spacing tokens are typically used in `margin`, `padding`, `gap`, and
> `{top,right,bottom,left}` properties.

### Fonts

Font tokens represent the font family of a text element. Its value is defined as
a string or an array of strings.

```tsx title="theme.ts"


export export const tokens = defineTokens({
  fonts: {
    body: { value: "Inter, sans-serif" },
    heading: { value: ["Roboto Mono", "sans-serif"] },
  },
})
```

> Font tokens are typically used in `font-family` property.

### Font Sizes

Font size tokens represent the size of a text element. Its value is defined as a
string.

```tsx title="theme.ts"


export export const tokens = defineTokens({
  fontSizes: {
    sm: { value: "12px" },
  },
})
```

> Font size tokens are typically used in `font-size` property.

### Font Weights

Font weight tokens represent the weight of a text element. Its value is defined
as a string.

```tsx title="theme.ts"


export const tokens = defineTokens({
  fontWeights: {
    bold: { value: "700" },
  },
})
```

> Font weight tokens are typically used in `font-weight` property.

### Letter Spacings

Letter spacing tokens represent the spacing between letters in a text element.
Its value is defined as a string.

```tsx


export const tokens = defineTokens({
  letterSpacings: {
    wide: { value: "0.1em" },
  },
})
```

> Letter spacing tokens are typically used in `letter-spacing` property.

### Line Heights

Line height tokens represent the height of a line of text. Its value is defined
as a string.

```tsx title="theme.ts"


export const tokens = defineTokens({
  lineHeights: {
    normal: { value: "1.5" },
  },
})
```

> Line height tokens are typically used in `line-height` property.

### Radii

Radii tokens represent the radius of a border. Its value is defined as a string.

```tsx title="theme.ts"


export const tokens = defineTokens({
  radii: {
    sm: { value: "4px" },
  },
})
```

> Radii tokens are typically used in `border-radius` property.

### Borders

A border is a line surrounding a UI element. You can define them as string
values or as a composite value

```tsx title="theme.ts"


export const tokens = defineTokens({
  borders: {
    // string value
    subtle: { value: "1px solid red" },
    // string value with reference to color token
    danger: { value: "1px solid {colors.red.400}" },
    // composite value
    accent: { value: { width: "1px", color: "red", style: "solid" } },
  },
})
```

> Border tokens are typically used in `border`, `border-top`, `border-right`,
> `border-bottom`, `border-left`, `outline` properties.

### Border Widths

Border width tokens represent the width of a border. Its value is defined as a
string.

```tsx title="theme.ts"


export const tokens = defineTokens({
  borderWidths: {
    thin: { value: "1px" },
    thick: { value: "2px" },
    medium: { value: "1.5px" },
  },
})
```

### Shadows

Shadow tokens represent the shadow of an element. Its value is defined as single
or multiple values containing a string or a composite value.

```tsx title="theme.ts"


export const tokens = defineTokens({
  shadows: {
    // string value
    subtle: { value: "0 1px 2px 0 rgba(0, 0, 0, 0.05)" },
    // composite value
    accent: {
      value: {
        offsetX: 0,
        offsetY: 4,
        blur: 4,
        spread: 0,
        color: "rgba(0, 0, 0, 0.1)",
      },
    },
    // multiple string values
    realistic: {
      value: [
        "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
        "0 1px 4px 0 rgba(0, 0, 0, 0.1)",
      ],
    },
  },
})
```

> Shadow tokens are typically used in `box-shadow` property.

### Easings

Easing tokens represent the easing function of an animation or transition. Its
value is defined as a string or an array of values representing the cubic
bezier.

```tsx title="theme.ts"


export const tokens = defineTokens({
  easings: {
    // string value
    easeIn: { value: "cubic-bezier(0.4, 0, 0.2, 1)" },
    // array value
    easeOut: { value: [0.4, 0, 0.2, 1] },
  },
})
```

> Ease tokens are typically used in `transition-timing-function` property.

### Opacity

Opacity tokens help you set the opacity of an element.

```tsx title="theme.ts"


export const tokens = defineTokens({
  opacity: {
    50: { value: 0.5 },
  },
})
```

> Opacity tokens are typically used in `opacity` property.

### Z-Index

This token type represents the depth of an element's position on the z-axis.

```tsx title="theme.ts"


export const tokens = defineTokens({
  zIndex: {
    modal: { value: 1000 },
  },
})
```

> Z-index tokens are typically used in `z-index` property.

### Assets

Asset tokens represent a url or svg string. Its value is defined as a string or
a composite value.

```ts
type CompositeAsset = { type: "url" | "svg"; value: string }
type Asset = string | CompositeAsset
```

```tsx title="theme.ts"


export const tokens = defineTokens({
  tokens: {
    assets: {
      logo: {
        value: { type: "url", value: "/static/logo.png" },
      },
      checkmark: {
        value: { type: "svg", value: "<svg>...</svg>" },
      },
    },
  },
})
```

> Asset tokens are typically used in `background-image` property.

### Durations

Duration tokens represent the length of time in milliseconds an animation or
animation cycle takes to complete. Its value is defined as a string.

```tsx title="theme.ts"


export const tokens = defineTokens({
  durations: {
    fast: { value: "100ms" },
  },
})
```

> Duration tokens are typically used in `transition-duration` and
> `animation-duration` properties.

### Animations

Animation tokens represent a keyframe animation. Its value is defined as a
string value.

```tsx title="theme.ts"


export const tokens = defineTokens({
  animations: {
    spin: {
      value: "spin 1s linear infinite",
    },
  },
})
```

> Animation tokens are typically used in `animation` property.

### Aspect Ratios

Aspect ratio tokens represent the aspect ratio of an element. Its value is
defined as a string.

```tsx title="theme.ts"


export const tokens = defineTokens({
  aspectRatios: {
    "1:1": { value: "1 / 1" },
    "16:9": { value: "16 / 9" },
  },
})
```


---
## typography

---
title: Typography
description: A list of typography tokens available in Cerberus.
---



## Font Tokens

Cerberus provides a set of **font tokens** (`theme.tokens.fonts`) that define the font families used throughout the design system. These font tokens serve as the foundation for all text styles and typography decisions.

<FontTokensGroup />

Font tokens are designed to be semantic and descriptive:
- `display` - Primary font reserved for display headings (Poppins)
- `sans` - Primary font used for body text and regular headings (Poppins)  
- `mono` - Monospace font used for code and technical content (Recursive)

**Customizing Font Tokens:**

Font tokens can be customized in two ways: at the Panda config level or through CSS custom properties.

**Option 1: Panda Config Level**

Override font tokens directly in your `panda.config.ts` file:

```tsx title="panda.config.ts"
import {
  createCerberusConfig,
  createCerberusPreset,
} from '@cerberus/panda-preset'

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

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

  theme: {
    tokens: {
      fonts: {
        // Override existing tokens
        display: { value: "Inter Display, sans-serif" },
        sans: { value: "Inter, system-ui, sans-serif" },
        mono: { value: "JetBrains Mono, Menlo, monospace" },
        
        // Add new font tokens
        brand: { value: "YourBrand Font, serif" },
      },
    },
  },
})
```

**Option 2: CSS Custom Properties**

Font tokens reference CSS custom properties with fallbacks for flexibility:
- Each token uses the pattern: `var(--font-{name}, var(--font-{family}, {fallback}))`
- You can override fonts by setting the appropriate CSS custom properties in your application

```css
:root {
  --font-display: "Custom Display Font", sans-serif;
  --font-sans: "Custom Body Font", system-ui, sans-serif;
  --font-mono: "Custom Mono Font", Menlo, monospace;
}
```

## Text Styles

Cerberus provides a comprehensive set of text styles that combine font families, sizes, weights, and spacing to create consistent typography patterns.

**Text Style Categories:**
- **Display** - Large headings for marketing and hero sections
- **Heading** - Structured content headings (h1-h6) 
- **Body** - Main content text in various sizes
- **Label** - Form labels and UI text
- **Button** - Button text styling
- **Mono** - Monospace text for code and technical content

**How to Use Text Styles:**
Text styles can be applied using the `textStyle` prop on Text components or through PandaCSS:

```tsx
// Using Text component
<Text textStyle="heading-lg">Large Heading</Text>

// Using Cerberus Primitive
<cerberus.p textStyle="body-md">Body Text</cerberus.p>

// Using CSS function
<p className={css({ textStyle: 'body-md' })}>Body text</p>
```

**Customization:**
- Text styles are built from primitive font and sizing tokens
- Override individual properties by extending the text style object
- Create custom text styles following the same pattern for consistency


---
## z-index

---
title: Z-Index
description: The z-index property controls the vertical stacking order of elements that overlap.
---



## Tokens

Cerberus provides the following z-index tokens:

`theme.tokens.zIndex`

<ZList />