# Style your app

Learn how to style UI components in 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](https://docs.stripe.com/stripe-apps/style.md#custom-styles).
- Other components have [preset styles](https://docs.stripe.com/stripe-apps/style.md#preset-styles) which you can sometimes adjust.

## Custom styles

The [Box](https://docs.stripe.com/stripe-apps/components/box.md) and [Inline](https://docs.stripe.com/stripe-apps/components/inline.md) 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.

Unlike in vanilla CSS, you can’t choose arbitrary font faces and styles. Use the `font` and `fontWeight` properties. For more information, see [Typography](https://docs.stripe.com/stripe-apps/style.md#typograpphy).

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](https://docs.stripe.com/stripe-apps/style.md#layout).

```jsx
<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 color of a [Box](https://docs.stripe.com/stripe-apps/components/box.md) or [Inline](https://docs.stripe.com/stripe-apps/components/inline.md) component, use the CSS `backgroundColor` property:

```jsx
<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](https://docs.stripe.com/stripe-apps/components/box.md) or [Inline](https://docs.stripe.com/stripe-apps/components/inline.md) component, use the CSS `keyline` property:

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

Use the following tokens as values for `keyline`:

### Text and icons

To set a color for all text or icons in a [Box](https://docs.stripe.com/stripe-apps/components/box.md) or [Inline](https://docs.stripe.com/stripe-apps/components/inline.md) component, use the CSS `color` property:

```jsx
<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.

```jsx
<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](https://docs.stripe.com/stripe-apps/components/box.md) or [Inline](https://docs.stripe.com/stripe-apps/components/inline.md) component, use the custom `font` property:

```jsx
<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](https://docs.stripe.com/stripe-apps/components/box.md) component, use the `textOverflow`, `overflow`, `whiteSpace`,  and `overflowWrap` properties:

```jsx
<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](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Text/Wrapping_Text).

### Text transformation

You can transform text in a [Box](https://docs.stripe.com/stripe-apps/components/box.md) or [Inline](https://docs.stripe.com/stripe-apps/components/inline.md) component using the `textTransform` property:

```jsx
<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](https://developer.mozilla.org/en-US/docs/Web/CSS/text-transform) for the full list.

### Text alignment

You can change the alignment of text in a [Box](https://docs.stripe.com/stripe-apps/components/box.md) component using the `textAlign` property:

```jsx
<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](https://docs.stripe.com/stripe-apps/components/box.md) component to control layout for its children. Other containers, like [List](https://docs.stripe.com/stripe-apps/components/list.md), handle layout automatically.

We conceptualize layouts as “stacks.”

### Horizontal stacks

To stack elements horizontally and match widths:

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

To stack elements horizontally with fractional widths:

```jsx
<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:

```jsx
<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:

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

To distribute elements:

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

To align elements to the end with a gap:

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

To vertically align elements to the bottom:

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

To include dividers between elements:

```jsx
<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:

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

To have a different horizontal and vertical gap:

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

To center elements horizontally while wrapping:

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

To center elements vertically while wrapping:

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

### Vertical stacks

To stack elements vertically and match widths:

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

To stack elements vertically while centering horizontally:

```jsx
<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:

```jsx
<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

| Property                | Values                                                              |
| ----------------------- | ------------------------------------------------------------------- |
| `alignX`                | `'start' | 'center' | 'end' | 'stretch'`                            |
| `alignY`                | `'top' | 'center' | 'baseline' | 'bottom' | 'stretch'`              |
| `distribute`            | `'space-between' | 'packed'`                                        |
| `gap`                   | See [Spacing](https://docs.stripe.com/stripe-apps/style.md#spacing) |
| `overflowX | overflowY` | `'visible' | 'hidden' | 'scroll' | 'auto'`                          |
| `stack`                 | `'x' | 'y' | 'z'`                                                   |
| `wrap`                  | `'wrap'`                                                            |

## Spacing

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

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

| Token     | Value |
| --------- | ----- |
| `0`       | 0px   |
| `xxsmall` | 2px   |
| `xsmall`  | 4px   |
| `small`   | 8px   |
| `medium`  | 16px  |
| `large`   | 24px  |
| `xlarge`  | 32px  |
| `xxlarge` | 48px  |

## Sizing

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

```jsx
<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.

| Token                                                                                    | Value                                                                                                        |
| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `0`                                                                                      | 0px                                                                                                          |
| `1/2`                                                                                    | 50%                                                                                                          |
| `1/3`, `2/3`                                                                             | 33.333333%, 66.666667%                                                                                       |
| `1/4`, `2/4`, `3/4`,                                                                     | 25%, 50%, 75%                                                                                                |
| `1/5`, `2/5`, `3/5`, `4/5`                                                               | 20%, 40%, 60%, 80%                                                                                           |
| `1/6`, `2/6`, `3/6`, `4/6`, `5/6`                                                        | 16.666667%, 33.333333%, 50%, 66.666667%, 83.333333%                                                          |
| `1/12`, `2/12`, `3/12`, `4/12`, `5/12`, `6/12`, `7/12`, `8/12`, `9/12`, `10/12`, `11/12` | 8.333333%, 16.666667%, 25%, 33.333333%, 41.666667%, 50%, 58.333333%, 66.666667%, 75%, 83.333333%, 91.666667% |
| `fill`                                                                                   | 100%                                                                                                         |

### Content-based sizing

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

| Token | Usage                                                                                                                                                                      |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `min` | Content inside the component takes all wrapping opportunities, becoming as small as the longest contents.                                                                  |
| `max` | Represents the maximum possible width of the content. When applied to text, the text won’t wrap, even if it causes the text to extend outside the bounds of its container. |
| `fit` | Fills the available space, but only up to the maximum size of the content.                                                                                                 |

## 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](https://docs.stripe.com/stripe-apps/components/chip.md) automatically change their appearance depending on what callbacks they implement. This helps the user understand their behavior. To avoid confusion, you can’t override these details.

### Several presets

Some components, like [Buttons](https://docs.stripe.com/stripe-apps/components/button.md), have a few styles you can select using a prop. See the documentation for each component for details.

### Limited CSS

Some components support specific CSS properties. For example, [Icons](https://docs.stripe.com/stripe-apps/components/icon.md) support color using the `fill` property. See the documentation for each component for details.

## See also

- [Extension SDK API reference](https://docs.stripe.com/stripe-apps/reference/extensions-sdk-api.md)
- [Stripe Apps UI Components](https://docs.stripe.com/stripe-apps/components.md)
- [Build a UI](https://docs.stripe.com/stripe-apps/build-ui.md)