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.

Layout
NameTypeDescription
flexResponsive<stringnumberboolean>When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
flexGrowResponsive<number>When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
flexShrinkResponsive<number>When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
flexBasisResponsive<numberstring>When used in a flex layout, specifies the initial main size of the element. See MDN.
alignSelfResponsive<'auto''normal''start''end''center''flex-start''flex-end''self-start''self-end''stretch'>Overrides the alignItems property of a flex or grid container. See MDN.
justifySelfResponsive<'auto''normal''start''end''flex-start''flex-end''self-start''self-end''center''left''right''stretch'>Specifies how the element is justified inside a flex or grid container. See MDN.
orderResponsive<number>The layout order for the element within a flex or grid container. See MDN.
gridAreaResponsive<string>When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
gridColumnResponsive<string>When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
gridRowResponsive<string>When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
gridColumnStartResponsive<string>When used in a grid layout, specifies the starting column to span within the grid. See MDN.
gridColumnEndResponsive<string>When used in a grid layout, specifies the ending column to span within the grid. See MDN.
gridRowStartResponsive<string>When used in a grid layout, specifies the starting row to span within the grid. See MDN.
gridRowEndResponsive<string>When used in a grid layout, specifies the ending row to span within the grid. See MDN.
Spacing
NameTypeDescription
marginResponsive<DimensionValue>The margin for all four sides of the element. See MDN.
marginTopResponsive<DimensionValue>The margin for the top side of the element. See MDN.
marginBottomResponsive<DimensionValue>The margin for the bottom side of the element. See MDN.
marginStartResponsive<DimensionValue>The margin for the logical start side of the element, depending on layout direction. See MDN.
marginEndResponsive<DimensionValue>The margin for the logical end side of an element, depending on layout direction. See MDN.
marginXResponsive<DimensionValue>The margin for both the left and right sides of the element. See MDN.
marginYResponsive<DimensionValue>The margin for both the top and bottom sides of the element. See MDN.
Sizing
NameTypeDescription
widthResponsive<DimensionValue>The width of the element. See MDN.
minWidthResponsive<DimensionValue>The minimum width of the element. See MDN.
maxWidthResponsive<DimensionValue>The maximum width of the element. See MDN.
heightResponsive<DimensionValue>The height of the element. See MDN.
minHeightResponsive<DimensionValue>The minimum height of the element. See MDN.
maxHeightResponsive<DimensionValue>The maximum height of the element. See MDN.
Positioning
NameTypeDescription
positionResponsive<'static''relative''absolute''fixed''sticky'>Specifies how the element is positioned. See MDN.
topResponsive<DimensionValue>The top position for the element. See MDN.
bottomResponsive<DimensionValue>The bottom position for the element. See MDN.
leftResponsive<DimensionValue>The left position for the element. See MDN. Consider using start instead for RTL support.
rightResponsive<DimensionValue>The right position for the element. See MDN. Consider using start instead for RTL support.
startResponsive<DimensionValue>The logical start position for the element, depending on layout direction. See MDN.
endResponsive<DimensionValue>The logical end position for the element, depending on layout direction. See MDN.
zIndexResponsive<number>The stacking order for the element. See MDN.
isHiddenResponsive<boolean>Hides the element.

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.

NameTypeDefaultDescription
colorVersionColorVersion5The Spectrum color token version number.
Layout
NameTypeDescription
overflowResponsive<string>Species what to do when the element's content is too long to fit its size. See MDN.
Spacing
NameTypeDescription
paddingResponsive<DimensionValue>The padding for all four sides of the element. See MDN.
paddingTopResponsive<DimensionValue>The padding for the top side of the element. See MDN.
paddingBottomResponsive<DimensionValue>The padding for the bottom side of the element. See MDN.
paddingStartResponsive<DimensionValue>The padding for the logical start side of the element, depending on layout direction. See MDN.
paddingEndResponsive<DimensionValue>The padding for the logical end side of an element, depending on layout direction. See MDN.
paddingXResponsive<DimensionValue>The padding for both the left and right sides of the element. See MDN.
paddingYResponsive<DimensionValue>The padding for both the top and bottom sides of the element. See MDN.
Background
NameTypeDescription
backgroundColorResponsive<BackgroundColor[ColorVersion]>The background color for the element.
Borders
NameTypeDescription
borderWidthResponsive<BorderSizeValue>The width of the element's border on all four sides. See MDN.
borderStartWidthResponsive<BorderSizeValue>The width of the border on the logical start side, depending on the layout direction. See MDN.
borderEndWidthResponsive<BorderSizeValue>The width of the border on the logical end side, depending on the layout direction. See MDN.
borderTopWidthResponsive<BorderSizeValue>The width of the top border. See MDN.
borderBottomWidthResponsive<BorderSizeValue>The width of the bottom border. See MDN.
borderXWidthResponsive<BorderSizeValue>The width of the left and right borders. See MDN.
borderYWidthResponsive<BorderSizeValue>The width of the top and bottom borders. See MDN.
borderColorResponsive<BorderColor[ColorVersion]>The color of the element's border on all four sides. See MDN.
borderStartColorResponsive<BorderColor[ColorVersion]>The color of the border on the logical start side, depending on the layout direction. See MDN.
borderEndColorResponsive<BorderColor[ColorVersion]>The color of the border on the logical end side, depending on the layout direction. See MDN.
borderTopColorResponsive<BorderColor[ColorVersion]>The color of the top border. See MDN.
borderBottomColorResponsive<BorderColor[ColorVersion]>The color of the bottom border. See MDN.
borderXColorResponsive<BorderColor[ColorVersion]>The color of the left and right borders. See MDN.
borderYColorResponsive<BorderColor[ColorVersion]>The color of the top and bottom borders. See MDN.
borderRadiusResponsive<BorderRadiusValue>The border radius on all four sides of the element. See MDN.
borderTopStartRadiusResponsive<BorderRadiusValue>The border radius for the top start corner of the element, depending on the layout direction. See MDN.
borderTopEndRadiusResponsive<BorderRadiusValue>The border radius for the top end corner of the element, depending on the layout direction. See MDN.
borderBottomStartRadiusResponsive<BorderRadiusValue>The border radius for the bottom start corner of the element, depending on the layout direction. See MDN.
borderBottomEndRadiusResponsive<BorderRadiusValue>The border radius for the bottom end corner of the element, depending on the layout direction. See MDN.

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.