Tag

The Tag component is used to display labels or tags with various styles and functionalities.

import { Tag } from '@cerberus/react'

Basic Usage

You can mix and match all of the examples to create the tag style of your choosing.

FilledStart iconEnd icon

import { Tag } from '@cerberus/react'
import { Information } from '@carbon/icons-react'
import { HStack } from 'styled-system/jsx'

function BasicTagPreview() {
  return (
    <HStack gap="md">
      <Tag>Filled</Tag>

      <Tag>
        <Information />
        Start icon
      </Tag>

      <Tag>
        End icon
        <Information />
      </Tag>
    </HStack>
  )
}

Usage Variants

Tags come in two usage variants: outlined and filled.

FilledOutlined

import { Tag } from '@cerberus/react'
import { HStack } from 'styled-system/jsx'

function UsageTagPreview() {
  return (
    <HStack gap="md">
      <Tag usage="filled">Filled</Tag>
      <Tag usage="outlined">Outlined</Tag>
    </HStack>
  )
}

Shape Variants

Tags come in two shape variants: square and pill.

PillSquare

import { Tag } from '@cerberus/react'
import { HStack } from 'styled-system/jsx'

function ShapeTagPreview() {
  return (
    <HStack gap="md">
      <Tag shape="pill">Pill</Tag>
      <Tag shape="square">Square</Tag>
    </HStack>
  )
}

Colors

You can set the color of the tag by using the palette prop. By nature of CSS rules, only one of palette or gradient can be used at a time.

page:

Label

secondaryAction:

Label

info:

Label

success:

Label

warning:

Label

danger:

Label

const palettes = [
  'page',
  'secondaryAction',
  'info',
  'success',
  'warning',
  'danger',
]
const variants = [
  { usage: 'filled', shape: 'pill' },
  { usage: 'outlined', shape: 'pill' },
  { usage: 'filled', shape: 'square' },
  { usage: 'outlined', shape: 'square' },
]
const COLOR_LIST = palettes.map((palette) => ({ palette, variants }))

export function OverviewPaletteTagPreview() {
  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((variant, idx) => (
            <GridItem key={`${palette}-${idx}`} colSpan={1}>
              <Tag
                palette={palette}
                usage={variant.usage}
                shape={variant.shape}
              >
                <Information />
                Label
              </Tag>
            </GridItem>
          ))}
        </Fragment>
      ))}
    </Grid>
  )
}

Gradients

You can set the gradient of the tag by using the gradient prop. By nature of CSS rules, only one of palette or gradient can be used at a time.

charon-light:

Label

charon-dark:

Label

nyx-light:

Label

nyx-dark:

Label

amphiaraus-light:

Label

amphiaraus-dark:

Label

styx-light:

Label

styx-dark:

Label

thanatos-light:

Label

thanatos-dark:

Label

hades-light:

Label

hades-dark:

Label

asphodel-light:

Label

asphodel-dark:

Label

function OverviewGradientTagPreview() {
  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((variant, idx) => (
            <GridItem key={`${gradient}-${idx}`} colSpan={1}>
              <Tag
                gradient={gradient}
                usage={variant.usage}
                shape={variant.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.

ClosableClosableClosable

'use client'

import { Tag } from '@cerberus/react'
import { HStack } from 'styled-system/jsx'

function ClosableTagPreview() {
  const handleClose = () => {
    console.log('Tag closed')
  }

  return (
    <HStack gap="md">
      <Tag onClick={handleClick}>Closable</Tag>

      <Tag palette="page" onClick={handleClick}>
        Closable
      </Tag>

      <Tag palette="danger" onClick={handleClick}>
        Closable
      </Tag>
    </HStack>
  )
}

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.

Cerberus Forever

import { Tag } from '@cerberus/react'

export function CustomTagPreview() {
  return (
    <Tag colorPalette="danger" p="2" rounded="0!" transform="skew(-10deg)">
      Cerberus Forever
    </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.

Dynamic Tags

Sometimes you may want to create Tags based on dynamic variables. In order to do this in a reliable way, we recommend using the Interface pattern.

import { Tag, type TagProps } from '@cerberus/react'

/**
 * This interface returns palette-based tags in a reliable way that PandaCSS
 * can statically analyze.
*/
export function MatchPaletteTag(props: TagProps) {
  switch (props.palette) {
    case 'page':
      return <Tag palette="page" {...props} />
    case 'secondaryAction':
      return <Tag palette="secondaryAction" {...props} />
    case 'info':
      return <Tag palette="info" {...props} />
    case 'success':
      return <Tag palette="success" {...props} />
    case 'warning':
      return <Tag palette="warning" {...props} />
    case 'danger':
      return <Tag palette="danger" {...props} />

    default:
      throw new Error(`Unsupported palette: ${props.palette}`)
  }
}

Likewise, you can achieve this same result creating a component with the exact name as the recipe:

import { Tag as CerbyTag, type TagProps as CerbyTagProps } from '@cerberus/react'

export function Tag(props: CerbyTagProps) {
  return <CerbyTag {...props} />
}

Because this component is named Tag, PandaCSS will allow dynamic styling for the properties. This only happens when you create components that are named the same as the recipe.

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.

On this page

Edit this page on Github