Style your app

You can style a Stripe App using design tokens that we provide. This helps you match the Dashboard visually, provide consistency, and maintain a high quality bar.

• The Box and Inline components support custom styles.
• Other components have preset styles which you can sometimes adjust.

Custom styles

The Box and Inline components support custom styles. Box and Inline are styleable containers like HTML div and span. To style them, use their css prop. They use CSS syntax, with a few differences from vanilla CSS.

<Box
  css={{
    padding: 'xxlarge',
    color: 'secondary',
    backgroundColor: 'container',
    borderRadius: 'small',
  }}
>
  This is a box.
</Box>

Unlike in vanilla CSS, you can’t choose arbitrary font faces and styles. Use the font and fontWeight properties. For more information, see Typography.

<Inline css={{font: 'body', color: 'primary', fontWeight: 'semibold'}}>
  This text is emphasized
</Inline>

Layout also works differently than it does in vanilla CSS. Instead, Stripe Apps use the same layout system Stripe uses internally. For more information, see Layout.

<Box
  css={{
    stack: 'x',
    gap: 'medium',
  }}
>
  <Box css={{width: '1/4', padding: 'medium', keyline: 'neutral'}} />
  <Box css={{width: '3/4', padding: 'medium', keyline: 'neutral'}} />
</Box>

All styling tokens are exposed through TypeScript, which means you’ll get a dropdown in your editor to autocomplete from the available values.

Color

Set colors in your custom styles by using the following values.

Backgrounds

To set the background colour of a Box or Inline component, use the CSS backgroundColor property:

<Box css={{ backgroundColor: 'container' }}>
  Box with a darker background.
</Box>

Use the following tokens as values for backgroundColor:

Borders

To add a border to a Box or Inline component, use the CSS keyline property:

<Box css={{ keyline: 'neutral' }}>
  Box with a neutral border.
</Box>

Use the following tokens as values for keyline:

Text & icons

To set a colour for all text or icons in a Box or Inline component, use the CSS color property:

<Box css={{ color: 'success' }}>
  Box with green text.
</Box>

For an icon that contrasts with the other children of its container, use fill. Otherwise, icons match the text around them.

<Box css={{ color: 'primary' }}>
  <Icon css={{ fill: 'success' }}/>
  Box with normal text and a green icon.
</Box>

Use the following tokens as values for color and fill:

Typography

To change the style of text in a Box or Inline component, use the custom font property:

<Inline css={{font: 'heading'}}>Heading</Inline>

The following styles are available:

Text overflow and wrapping

To change how overflow text is handled in a Box component, use the textOverflow, overflow, whiteSpace, and overflowWrap properties:

<Box css={{textOverflow: 'ellipsis', overflow: 'hidden', overflowWrap: 'normal'}}>
  Box where long text is cut off with an ellipsis
</Box>

For for more overflow and text wrapping scenarios, see Wrapping and Breaking Text.

Text transformation

You can transform text in a Box or Inline component using the textTransform property:

<Box css={{textTransform: 'uppercase'}}>
  Box where all text appears uppercase
</Box>

Here are some common values that can be used for the textTransform property:

See text-transform for the full list.

Text alignment

You can change the alignment of text in a Box component using the textAlign property:

<Box css={{textAlign: 'center'}}>
  Box where text is centered
</Box>

Use the following token values for textAlign:

Layout

The Stripe Apps layout styling API allows you to write styles that can take advantage of our design tokens and includes other improvements over vanilla CSS. Use these tokens in a Box component to control layout for its children. Other containers, like List, handle layout automatically.

We conceptualize layouts as “stacks.”

Horizontal stacks

To stack elements horizontally and match widths:

<Box
  css={{
    stack: 'x',
    gap: 'medium',
    alignX: 'stretch', // This is the default and can be omitted
  }}
>

To stack elements horizontally with fractional widths:

<Box
  css={{
    stack: 'x',
    gap: 'medium',
  }}
>
  <Box css={{width: '1/4', padding: 'medium', keyline: 'neutral'}} />
  <Box css={{width: '3/4', padding: 'medium', keyline: 'neutral'}} />
</Box>

To stack elements horizontally with a fractional width for one element and the rest of the elements stretched:

<Box
  css={{
    stack: 'x',
    gap: 'medium',
  }}
>
  <Box css={{padding: 'medium', keyline: 'neutral'}} />
  <Box css={{width: '1/4', padding: 'medium', keyline: 'neutral'}} />
  <Box css={{padding: 'medium', keyline: 'neutral'}} />
</Box>

To align elements to the start with a gap:

<Box
  css={{
    stack: 'x',
    gap: 'medium',
    alignX: 'start',
  }}
>

To distribute elements:

<Box
  css={{
    stack: 'x',
    distribute: 'space-between',
  }}
>

To align elements to the end with a gap:

<Box
  css={{
    stack: 'x',
    gap: 'medium',
    alignX: 'end',
  }}
>

To vertically align elements to the bottom:

<Box
  css={{
    stack: 'x',
    gap: 'medium',
    alignX: 'start',
    alignY: 'bottom',
  }}
>

To include dividers between elements:

<Box
  css={{
    stack: 'x',
    gap: 'small',
    alignX: 'start',
  }}
>
  <Box css={{padding: 'medium', keyline: 'neutral'}} />
  <Divider />
  <Box css={{padding: 'medium', keyline: 'neutral'}} />
  <Divider />
  <Box css={{padding: 'medium', keyline: 'neutral'}} />
</Box>

To wrap items into rows:

<Box
  css={{
    stack: 'x',
    gap: 'medium',
    wrap: 'wrap',
    alignX: 'start',
  }}
>

To have a different horizontal and vertical gap:

<Box
  css={{
    stack: 'x',
    gapX: 'small',
    gapY: 'large',
    wrap: 'wrap',
    alignX: 'start',
  }}
>

To center elements horizontally while wrapping:

<Box
  css={{
    stack: 'x',
    gap: 'medium',
    wrap: 'wrap',
    alignX: 'center',
  }}
>

To center elements vertically while wrapping:

<Box
  css={{
    stack: 'x',
    gap: 'medium',
    wrap: 'wrap',
    alignX: 'start',
    alignY: 'center',
  }}
>

Vertical stacks

To stack elements vertically and match widths:

<Box
  css={{
    stack: 'y',
    gap: 'medium',
  }}
>

To stack elements vertically while centering horizontally:

<Box
  css={{
    stack: 'y',
    gap: 'medium',
    alignX: 'center',
  }}
>
  <Box css={{width: '1/4', padding: 'medium', keyline: 'neutral'}} />
  <Box css={{width: '2/3', padding: 'medium', keyline: 'neutral'}} />
  <Box css={{width: '1/3', padding: 'medium', keyline: 'neutral'}} />
</Box>

Layered stacks

To display elements atop one another:

<Box
  css={{
    stack: 'z',
    alignX: 'center',
    alignY: 'center',
  }}
>
  <Box css={{padding: 'xxlarge', keyline: 'neutral'}} />
  <Box css={{padding: 'large', keyline: 'neutral'}} />
  <Box css={{padding: 'small', keyline: 'neutral'}} />
</Box>

Layout properties

Spacing

You can specify margins, padding, and layout gaps using the values listed below.

<Box css={{margin: 'small'}} />

Sizing

You can specify width and height using fractions or content-based sizing tokens.

<Box css={{width: '1/2'}} />

Fractional sizing

The available fractions include halves, thirds, quarters, fifths, sixths and, twelfths. The fill token enables a component to match the size of its container.

Content-based sizing

You can size a Box relative to the content within it.

Preset styles

Components other than Box and Inline have preset styles, which helps maintain consistency. You can sometimes control or override the presets in a specific way.

Automatic styling

Some components style themselves automatically. For example, Chips automatically change their appearance depending on what callbacks they implement. This helps the user understand their behaviour. To avoid confusion, you can’t override these details.

<Box
  css={{
    backgroundColor: 'surface',
    padding: 'medium',
    borderRadius: 'medium',
  }}
>
  <ChipList>
    <Chip
      label="Currency"
      value="USD"
      onDropdown={() => {
        console.log('Dropdown function triggered');
      }}
      onClose={() => {
        console.log('Close function triggered');
      }}
    />
    <Chip
      label="Status"
      value="Succeeded"
      onDropdown={() => {
        console.log('Dropdown function triggered');
      }}
      onClose={() => {
        console.log('Close function triggered');
      }}
    />
    <Chip
      label="Amount"
      onAddSuggestion={() => {
        console.log('Add Amount suggestion');
      }}
    />
    <Chip
      label="Date"
      onAddSuggestion={() => {
        console.log('Add Date suggestion');
      }}
    />
  </ChipList>
</Box>

Several presets

Some components, like Buttons, have a few styles you can select using a prop. See the documentation for each component for details.

<Button type="primary">Primary</Button>
<Button>Secondary</Button>
<Button type="destructive">Destructive</Button>

Limited CSS

Some components support specific CSS properties. For example, Icons support colour using the fill property. See the documentation for each component for details.

<Icon name="cancelCircle" css={{fill: 'critical'}} />