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
andInline
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.
Unlike in vanilla CSS, you can’t choose arbitrary font faces and styles. Use the font
and fontWeight
properties. For more information, see Typography.
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.
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 or Inline component, use the CSS backgroundColor
property:
Use the following tokens as values for backgroundColor
:
Example | Token | Usage |
---|---|---|
surface | Used for the background of apps | |
container | Used for cards and sections within an app |
Borders
To add a border to a Box or Inline component, use the CSS keyline
property:
Use the following tokens as values for keyline
:
Example | Token | Usage |
---|---|---|
neutral | The default color for all borders and dividers | |
critical | Used for content which is critically urgent to the user |
Text & icons
To set a color for all text or icons in a Box or Inline component, use the CSS color
property:
For an icon that contrasts with the other children of its container, use fill
. Otherwise, icons match the text around them.
Use the following tokens as values for color
and fill
:
Example | Token | Usage |
---|---|---|
primary | The default color for text and icons | |
secondary | Used to for text and icons which are less prominent | |
disabled | Used for elements which are disabled | |
info | Used for content that is neutral and informational | |
success | Used for content which indicates the success of some action | |
attention | Used for content which is should grab the user’s attention | |
critical | Used for content which is critically urgent to the user. Should be used sparingly. |
Typography
To change the style of text in a Box or Inline component, use the custom font
property:
The following styles are available:
Token | Usage | Example |
---|---|---|
heading | Used for labeling a section of your app | The quick brown fox jumps over the lazy dog. |
subheading | Used for labeling content within a section of your app | The quick brown fox jumps over the lazy dog. |
body | Primary body text of the app | The quick brown fox jumps over the lazy dog. |
caption | Used for text that should be less prominent than body text | The quick brown fox jumps over the lazy dog. |
Text overflow and wrapping
To change how overflow text is handled in a Box component, use the textOverflow
, overflow
, whiteSpace
, and overflowWrap
properties:
CSS | Usage | Example |
---|---|---|
{textOverflow: 'ellipsis', overflow: 'hidden', overflowWrap: 'normal'} | Used for adding an ellipsis (...) to text that overflows the available space | SupercalifragilisticexpialidociousSupercalifragilisticexpialidociousSupercalifragilisticexpialidocious |
{overflowWrap: 'break-word'} | Used for breaking up long words | SupercalifragilisticexpialidociousSupercalifragilisticexpialidocious |
{whiteSpace: 'nowrap'} | Used to prevent lines from wrapping | This text is too long for the container. |
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:
Here are some common values that can be used for the textTransform
property:
Token | Usage | Before | After |
---|---|---|---|
capitalize | Used to convert the first letter of each word to uppercase | Lorem ipsum dolor sit amet | Lorem ipsum dolor sit amet |
uppercase | Used to convert all letters to uppercase | Lorem ipsum dolor sit amet | Lorem ipsum dolor sit amet |
lowercase | Used to convert all letters to lowercase | Lorem ipsum dolor sit amet | Lorem ipsum dolor sit amet |
none | Used to prevent the case of letters from being changed | loREM iPSUm DOLor SIt AMet | loREM iPSUm DOLor SIt AMet |
See text-transform for the full list.
Text alignment
You can change the alignment of text in a Box component using the textAlign
property:
Use the following token values for textAlign
:
Token | Usage | Example |
---|---|---|
left | Used to algin text to the left | This text is left aligned |
right | Used to align text to the right | This text is right aligned |
start | Used align text to the start direction | This text is start aligned |
end | Used to align text to the end direction | This text is end aligned |
center | Used to center text | This text is centered |
justify | Used to justify text | This is some text that is justified |
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:
To stack elements horizontally with fractional widths:
To stack elements horizontally with a fractional width for one element and the rest of the elements stretched:
To align elements to the start with a gap:
To distribute elements:
To align elements to the end with a gap:
To vertically align elements to the bottom:
To include dividers between elements:
To wrap items into rows:
To have a different horizontal and vertical gap:
To center elements horizontally while wrapping:
To center elements vertically while wrapping:
Vertical stacks
To stack elements vertically and match widths:
To stack elements vertically while centering horizontally:
Layered stacks
To display elements atop one another:
Layout properties
Property | Values |
---|---|
alignX | 'start' | 'center' | 'end' | 'stretch' |
alignY | 'top' | 'center' | 'baseline' | 'bottom' | 'stretch' |
distribute | 'space-between' | 'packed' |
gap | See 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.
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.
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 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, 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 support color using the fill
property. See the documentation for each component for details.