Component Variants

Components use custom variants to allow you to completely customize the look and feel of each component.

The following table lists each component's variant group and default variant name where applicable.

The following components support the variant prop, but do not include default variant keys.

• Box
• Flex
• Donut
• Spinner
• Embed
• AspectRatio
• AspectImage

Additional variants can be added to each group to create multiple styles for a single component. For example, a secondary button style can be added to theme.buttons.secondary then applied to any Button using the variant prop.

// example using a variant
<Button variant="secondary">Secondary</Button>

Combining multiple variants

If you want to combine multiple variants on the same element, pass an array of variants with the variant prop. Variant styles are merged from left to right, so if some of the styles conflict, those of the variant passed later will render.

<Text variant={['caps', 'heading']}>Title text</Text>
<Text variant={['caps', 'heading']}>Title text</Text>

Variant as a function

If you need to determine variants at run-time, pass a function to the variant prop.

<Box
  variant={(theme) => {
    const buttonVariant = Object.keys(theme.buttons)[0]
    return `buttons.${buttonVariant}`
  }}>
  some text
</Box>
<Box
  variant={(theme) => {
    const buttonVariant = Object.keys(theme.buttons)[0]
    return `buttons.${buttonVariant}`
  }}>
  some text
</Box>

Example theme

// example theme
{
  // ...base theme...
  // After the base theme, define the variants:
  buttons: {
    secondary: {
      fontWeight: 'bold',
      color: 'white',
      bg: 'primary',
      '&:hover': {
        bg: 'dark',
      },
    },
  },
  text: {
    caps: {
      textTransform: 'uppercase',
      letterSpacing: '.2em',
    },
    heading: {
      fontFamily: 'heading',
      fontWeight: 'heading',
      lineHeight: 'heading',
    },
    display: {
      // extends the text.heading styles
      variant: 'text.heading',
      fontSize: [6, 7, 8],
      fontWeight: 'display',
    },
  },
  cards: {
    primary: {
      padding: 2,
      borderRadius: 4,
      boxShadow: '0 0 4px 1px rgba(0, 0, 0, 0.5)',
    },
  },
}