Styling

This page describes how styling works in React Spectrum, including how to customize spacing, sizing, and positioning, and how to create your own custom components using Spectrum styles.

Introduction#

React Spectrum components are designed to be consistent across all Adobe applications. They include built-in styling that has been considered carefully, and extensively tested. In general, customizing Spectrum design is discouraged, but most components do offer control over layout and other aspects. In addition, you can use Spectrum defined variables to ensure your application conforms to design requirements, and is adaptive across platform scales and color schemes.

Style props#

All React Spectrum components support a limited set of styling options, including layout, spacing, sizing, and positioning options. While internal component styles such as padding, colors, borders and text styles are included in Spectrum and not available to override, external styles like margins and sizes can be set on all components.

Supported styling options are available as props on every React Spectrum component. The following example shows a text field and a button. The text field has a custom width set on it, and the button has a margin before it.

<TextField label="Name" labelPosition="side" width="size-2000" />
<ActionButton marginStart="size-150">Submit</ActionButton>

<TextField
  label="Name"
  labelPosition="side"
  width="size-2000"
/>
<ActionButton marginStart="size-150">Submit</ActionButton>

<TextField
  label="Name"
  labelPosition="side"
  width="size-2000"
/>
<ActionButton marginStart="size-150">
  Submit
</ActionButton>

All of the available style props are listed below.

Dimension values#

Where applicable, each style property accepts Spectrum defined variables in addition to raw CSS values. Using Spectrum variables is preferred wherever possible. These variables conform to Spectrum design defined sizing and spacing requirements, and also automatically adapt on different devices. For example, on touch screen devices, all Spectrum components expand in size to give users larger hit targets.

The list of dimension values is visualized below. Use the picker to see how they change between desktop and mobile.

CSS functions#

Dimension variables may also be used as part of CSS functions like calc(), min(), and max(). This can be done by simply referring to the variable within the CSS expression. For example, you could make an element take up 100% of the width of it's container minus a certain dimension value.

<View
  width="calc(100% - size-2000)"
  height="single-line-height"
  backgroundColor="green-500"
/>

<View
  width="calc(100% - size-2000)"
  height="single-line-height"
  backgroundColor="green-500"
/>

<View
  width="calc(100% - size-2000)"
  height="single-line-height"
  backgroundColor="green-500"
/>

Responsive styles#

In addition to static values, all style props support object syntax to specify different values for the prop depending on the responsive breakpoint. By default, breakpoints are named following t-shirt sizing, and correspond to common device resolutions. Breakpoints can be overridden at the application level via the Provider component. In addition to breakpoints, a base value can be provided to style props, which will be applied when no breakpoints match.

In this example, the TextField has a default width of size-2000, which is overridden to size-5000 at the large breakpoint. Resize your browser window to see this in action.

<TextField label="Name" width={{ base: 'size-2000', L: 'size-5000' }} />

<TextField
  label="Name"
  width={{ base: 'size-2000', L: 'size-5000' }}
/>

<TextField
  label="Name"
  width={{
    base: 'size-2000',
    L: 'size-5000'
  }}
/>

React Spectrum's breakpoints are mobile first, which means style props apply at that breakpoint and above. For example, the L breakpoint is applied at screen sizes 1024px and wider. The base value should be used to specify the layout at the smallest possible screen size, and additional breakpoints may be added to adapt the layout for larger devices.

Responsive style props can also be used to adapt layouts on different screen sizes. Read more about this in the layout docs.

Custom components#

Sometimes, you may find yourself needing to build a component that doesn't exist in Spectrum yet. In these cases, you can ensure consistency with other Spectrum components by utilizing existing Spectrum variables. For example, there are Spectrum variables for colors, border sizes, paddings, etc.

These variables could be consumed in CSS directly, but if you're building something simple, you could consider using the View component from React Spectrum. View is like a div or span (depending on the elementType prop), but with additional style properties that map to Spectrum defined variables in addition to the ones covered above.

The following example shows how you might build a container element using Spectrum defined variables for the border and padding. Use the color scheme and scale pickers to see how the view changes automatically based on these variables.

<View
  borderWidth="thin"
  borderColor="dark"
  borderRadius="medium"
  padding="size-250">
  <TextField label="Name" />
</View>

<View
  borderWidth="thin"
  borderColor="dark"
  borderRadius="medium"
  padding="size-250">
  <TextField label="Name" />
</View>

<View
  borderWidth="thin"
  borderColor="dark"
  borderRadius="medium"
  padding="size-250"
>
  <TextField label="Name" />
</View>

All of the properties supported by View are listed below. All style properties covered previously are also supported.

Color values#

Style props that accept colors, such as backgrounds and borders, only accept Spectrum defined color values. In addition to ensuring consistency across products, Spectrum colors automatically adapt to color scheme changes, e.g. dark mode. Learn more about color on the Spectrum website.

There are two versions of Spectrum colors available: v5, and v6. v6 offers an expanded color palette, and we recommend using it for new projects. However, v5 is still the default for backward compatibility. You can use v6 colors in custom components by setting the colorVersion prop on the View component to 6. This controls the accepted values of other style props on the View, such as background and border colors. A color migration guide is also available on the Spectrum website to help you upgrade from v5 to v6.

The list of Spectrum color values is visualized below. Use the picker to see how they change between the light and dark color schemes.

Escape hatches#

While we encourage teams to utilize Spectrum design as it is, we do realize that sometimes product specific customizations may be needed. In these cases, we encourage you or your designers to talk to us. We may be able to suggest an alternative implementation strategy, or perhaps your design can help inform future Spectrum additions.

While the traditional className and style props are not supported in React Spectrum components, there are two escape hatches that you can use at your own risk. These are UNSAFE_className and UNSAFE_style. Use of these props should be considered a last resort. They can be used to work around bugs or limitations in React Spectrum, but should not be used in the long term.

The reasoning behind this is that future updates to Spectrum design may cause unintended breaking changes in products. If the internal DOM structure or CSS properties of a React Spectrum component change, this may lead to conflicts with CSS overrides in products. For this reason, className and style are unsafe, and if you use them know that you are doing so at your own risk.