Variants

View Source

Describe how component trees are styled throughout different states.

VariantProvider

This component is responsible for turning variants on/off. Any prop passed to this component is considered the key for a variant and will be activated when true.

variants prop

Box and Text primitive components, as well as any layout components, may pass a variants prop that describes styles at various points in time. When the respective key is activated in VariantProvider, the styles will be applied or overridden in the order they are written.

pseudo states

focus, hover, and active are reserved variant keys that will generate the respective pseudo state CSS. These may also be activated programatically by using VariantProvider.

Example

Variants work similar to CSS in that they will cascade down and any child can define the styling that will be applied when the respective variant is activated in the closest parent VariantProvider.

In a simple example we can model compact and hover states for a UI screen:

Normal

Heading

Model behavior throughout a tree of components.

I'm pink on hover.

Compact

Heading

Model behavior throughout a tree of components.

I'm pink on hover.

Compact & Hover

Heading

Model behavior throughout a tree of components.

I'm pink on hover.

Copy

Edit

function Screen() {
  return (
    <Card
      padding={4}
      spacing={1}
      variants={{ compact: { padding: 2, spacing: 0.5 } }}
    >
      <Heading
        fontSize={1}
        lineHeight="1"
        variants={{ compact: { fontSize: 2 } }}
      >
        Heading
      </Heading>
      <Text
        variants={{
          compact: { fontSize: 4 },
          hover: { color: 'primary' },
        }}
      >
        Model behavior throughout a tree of components.{' '}
        <Text inline variants={{ hover: { color: 'hotpink' } }}>
          I'm pink on hover.
        </Text>
      </Text>
    </Card>
  )
}

render(() => {
  return (
    <StackView spacing={2}>
      <Heading level={3}>Normal</Heading>
      <VariantProvider compact={false}>
        <Screen />
      </VariantProvider>
      <Heading level={3}>Compact</Heading>
      <VariantProvider compact={true}>
        <Screen />
      </VariantProvider>
      <Heading level={3}>Compact & Hover</Heading>
      <VariantProvider hover={true}>
        <Screen />
      </VariantProvider>
    </StackView>
  )
})

function Screen() {
  return (
    <Card
      padding={4}
      spacing={1}
      variants={{ compact: { padding: 2, spacing: 0.5 } }}
    >
      <Heading
        fontSize={1}
        lineHeight="1"
        variants={{ compact: { fontSize: 2 } }}
      >
        Heading
      </Heading>
      <Text
        variants={{
          compact: { fontSize: 4 },
          hover: { color: 'primary' },
        }}
      >
        Model behavior throughout a tree of components.{' '}
        <Text inline variants={{ hover: { color: 'hotpink' } }}>
          I'm pink on hover.
        </Text>
      </Text>
    </Card>
  )
}
render(() => {
  return (
    <StackView spacing={2}>
      <Heading level={3}>Normal</Heading>
      <VariantProvider compact={false}>
        <Screen />
      </VariantProvider>
      <Heading level={3}>Compact</Heading>
      <VariantProvider compact={true}>
        <Screen />
      </VariantProvider>
      <Heading level={3}>Compact & Hover</Heading>
      <VariantProvider hover={true}>
        <Screen />
      </VariantProvider>
    </StackView>
  )
})

VariantProvider
variants prop
pseudo states
Example

PreviousTheming NextColors