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"
  placeholder="John Smith"
  width="size-2000"
/>
<ActionButton marginStart="size-150">Submit</ActionButton>

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

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

All of the available style props are listed below.

Layout

Name	Type	Default	Description
`flex`	`string \| number \| boolean`	—	When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
`flexGrow`	`number`	—	When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
`flexShrink`	`number`	—	When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
`flexBasis`	`number \| string`	—	When used in a flex layout, specifies the initial main size of the element. See MDN.
`alignSelf`	`'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.
`justifySelf`	`'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.
`order`	`number`	—	The layout order for the element within a flex or grid container. See MDN.
`gridArea`	`string`	—	When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
`gridColumn`	`string`	—	When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
`gridRow`	`string`	—	When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
`gridColumnStart`	`string`	—	When used in a grid layout, specifies the starting column to span within the grid. See MDN.
`gridColumnEnd`	`string`	—	When used in a grid layout, specifies the ending column to span within the grid. See MDN.
`gridRowStart`	`string`	—	When used in a grid layout, specifies the starting row to span within the grid. See MDN.
`gridRowEnd`	`string`	—	When used in a grid layout, specifies the ending row to span within the grid. See MDN.

Spacing

Name	Type	Default	Description
`margin`	`DimensionValue`	—	The margin for all four sides of the element. See MDN.
`marginTop`	`DimensionValue`	—	The margin for the top side of the element. See MDN.
`marginBottom`	`DimensionValue`	—	The margin for the bottom side of the element. See MDN.
`marginStart`	`DimensionValue`	—	The margin for the logical start side of the element, depending on layout direction. See MDN.
`marginEnd`	`DimensionValue`	—	The margin for the logical end side of an element, depending on layout direction. See MDN.
`marginX`	`DimensionValue`	—	The margin for both the left and right sides of the element. See MDN.
`marginY`	`DimensionValue`	—	The margin for both the top and bottom sides of the element. See MDN.

Sizing

Name	Type	Default	Description
`width`	`DimensionValue`	—	The width of the element. See MDN.
`minWidth`	`DimensionValue`	—	The minimum width of the element. See MDN.
`maxWidth`	`DimensionValue`	—	The maximum width of the element. See MDN.
`height`	`DimensionValue`	—	The height of the element. See MDN.
`minHeight`	`DimensionValue`	—	The minimum height of the element. See MDN.
`maxHeight`	`DimensionValue`	—	The maximum height of the element. See MDN.

Positioning

Name	Type	Default	Description
`position`	`'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky'`	—	Specifies how the element is positioned. See MDN.
`top`	`DimensionValue`	—	The top position for the element. See MDN.
`bottom`	`DimensionValue`	—	The bottom position for the element. See MDN.
`left`	`DimensionValue`	—	The left position for the element. See MDN. Consider using `start` instead for RTL support.
`right`	`DimensionValue`	—	The right position for the element. See MDN. Consider using `start` instead for RTL support.
`start`	`DimensionValue`	—	The logical start position for the element, depending on layout direction. See MDN.
`end`	`DimensionValue`	—	The logical end position for the element, depending on layout direction. See MDN.
`zIndex`	`number`	—	The stacking order for the element. See MDN.
`isHidden`	`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.

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" labelPosition="side" placeholder="John Smith" />
  <ActionButton marginStart="size-150">Submit</ActionButton>
</View>

<View
  borderWidth="thin"
  borderColor="dark"
  borderRadius="medium"
  padding="size-250">
  <TextField
    label="Name"
    labelPosition="side"
    placeholder="John Smith"
  />
  <ActionButton marginStart="size-150">
    Submit
  </ActionButton>
</View>

<View
  borderWidth="thin"
  borderColor="dark"
  borderRadius="medium"
  padding="size-250">
  <TextField
    label="Name"
    labelPosition="side"
    placeholder="John Smith"
  />
  <ActionButton marginStart="size-150">
    Submit
  </ActionButton>
</View>

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

Layout

Name	Type	Default	Description
`overflow`	`string`	—	Species what to do when the element's content is too long to fit its size. See MDN.

Spacing

Name	Type	Default	Description
`padding`	`DimensionValue`	—	The padding for all four sides of the element. See MDN.
`paddingTop`	`DimensionValue`	—	The padding for the top side of the element. See MDN.
`paddingBottom`	`DimensionValue`	—	The padding for the bottom side of the element. See MDN.
`paddingStart`	`DimensionValue`	—	The padding for the logical start side of the element, depending on layout direction. See MDN.
`paddingEnd`	`DimensionValue`	—	The padding for the logical end side of an element, depending on layout direction. See MDN.
`paddingX`	`DimensionValue`	—	The padding for both the left and right sides of the element. See MDN.
`paddingY`	`DimensionValue`	—	The padding for both the top and bottom sides of the element. See MDN.

Background

Name	Type	Default	Description
`backgroundColor`	`BackgroundColorValue`	—	The background color for the element.

Borders

Name	Type	Default	Description
`borderWidth`	`BorderSizeValue`	—	The width of the element's border on all four sides. See MDN.
`borderStartWidth`	`BorderSizeValue`	—	The width of the border on the logical start side, depending on the layout direction. See MDN.
`borderEndWidth`	`BorderSizeValue`	—	The width of the border on the logical end side, depending on the layout direction. See MDN.
`borderTopWidth`	`BorderSizeValue`	—	The width of the top border. See MDN.
`borderBottomWidth`	`BorderSizeValue`	—	The width of the bottom border. See MDN.
`borderXWidth`	`BorderSizeValue`	—	The width of the left and right borders. See MDN.
`borderYWidth`	`BorderSizeValue`	—	The width of the top and bottom borders. See MDN.
`borderColor`	`BorderColorValue`	—	The color of the element's border on all four sides. See MDN.
`borderStartColor`	`BorderColorValue`	—	The color of the border on the logical start side, depending on the layout direction. See MDN.
`borderEndColor`	`BorderColorValue`	—	The color of the border on the logical end side, depending on the layout direction. See MDN.
`borderTopColor`	`BorderColorValue`	—	The color of the top border. See MDN.
`borderBottomColor`	`BorderColorValue`	—	The color of the bottom border. See MDN.
`borderXColor`	`BorderColorValue`	—	The color of the left and right borders. See MDN.
`borderYColor`	`BorderColorValue`	—	The color of the top and bottom borders. See MDN.
`borderRadius`	`BorderRadiusValue`	—	The border radius on all four sides of the element. See MDN.
`borderTopStartRadius`	`BorderRadiusValue`	—	The border radius for the top start corner of the element, depending on the layout direction. See MDN.
`borderTopEndRadius`	`BorderRadiusValue`	—	The border radius for the top end corner of the element, depending on the layout direction. See MDN.
`borderBottomStartRadius`	`BorderRadiusValue`	—	The border radius for the bottom start corner of the element, depending on the layout direction. See MDN.
`borderBottomEndRadius`	`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.

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.

See the Styling docs for a visualization of these values.

'size-0'
  | 'size-10'
  | 'size-25'
  | 'size-40'
  | 'size-50'
  | 'size-65'
  | 'size-75'
  | 'size-85'
  | 'size-100'
  | 'size-115'
  | 'size-125'
  | 'size-130'
  | 'size-150'
  | 'size-160'
  | 'size-175'
  | 'size-200'
  | 'size-225'
  | 'size-250'
  | 'size-300'
  | 'size-350'
  | 'size-400'
  | 'size-450'
  | 'size-500'
  | 'size-550'
  | 'size-600'
  | 'size-675'
  | 'size-700'
  | 'size-800'
  | 'size-900'
  | 'size-1000'
  | 'size-1200'
  | 'size-1250'
  | 'size-1600'
  | 'size-1700'
  | 'size-2000'
  | 'size-2400'
  | 'size-3000'
  | 'size-3400'
  | 'size-3600'
  | 'size-4600'
  | 'size-5000'
  | 'size-6000'
  | 'static-size-0'
  | 'static-size-10'
  | 'static-size-25'
  | 'static-size-50'
  | 'static-size-40'
  | 'static-size-65'
  | 'static-size-100'
  | 'static-size-115'
  | 'static-size-125'
  | 'static-size-150'
  | 'static-size-175'
  | 'static-size-200'
  | 'static-size-225'
  | 'static-size-250'
  | 'static-size-300'
  | 'static-size-400'
  | 'static-size-450'
  | 'static-size-500'
  | 'static-size-550'
  | 'static-size-600'
  | 'static-size-700'
  | 'static-size-800'
  | 'static-size-900'
  | 'static-size-1000'
  | 'static-size-1200'
  | 'static-size-1700'
  | 'static-size-2400'
  | 'static-size-2600'
  | 'static-size-3400'
  | 'static-size-3600'
  | 'static-size-4600'
  | 'static-size-5000'
  | 'static-size-6000'
  | 'single-line-height'
  | 'single-line-width'
  | string
    &  & {}
  | number

'default'
  | 'transparent'
  | 'label-gray'
  | ColorValue

'celery-400'
  | 'celery-500'
  | 'celery-600'
  | 'celery-700'
  | 'chartreuse-400'
  | 'chartreuse-500'
  | 'chartreuse-600'
  | 'chartreuse-700'
  | 'yellow-400'
  | 'yellow-500'
  | 'yellow-600'
  | 'yellow-700'
  | 'magenta-400'
  | 'magenta-500'
  | 'magenta-600'
  | 'magenta-700'
  | 'fuchsia-400'
  | 'fuchsia-500'
  | 'fuchsia-600'
  | 'fuchsia-700'
  | 'purple-400'
  | 'purple-500'
  | 'purple-600'
  | 'purple-700'
  | 'indigo-400'
  | 'indigo-500'
  | 'indigo-600'
  | 'indigo-700'
  | 'seafoam-400'
  | 'seafoam-500'
  | 'seafoam-600'
  | 'seafoam-700'
  | 'red-400'
  | 'red-500'
  | 'red-600'
  | 'red-700'
  | 'orange-400'
  | 'orange-500'
  | 'orange-600'
  | 'orange-700'
  | 'green-400'
  | 'green-500'
  | 'green-600'
  | 'green-700'
  | 'blue-400'
  | 'blue-500'
  | 'blue-600'
  | 'blue-700'
  | 'gray-50'
  | 'gray-75'
  | 'gray-100'
  | 'gray-200'
  | 'gray-300'
  | 'gray-400'
  | 'gray-500'
  | 'gray-600'
  | 'gray-700'
  | 'gray-800'
  | 'gray-900'
  | 'static-black'
  | 'static-white'
  | 'static-blue'
  | 'static-gray-50'
  | 'static-gray-75'
  | 'static-gray-100'
  | 'static-gray-200'
  | 'static-gray-300'
  | 'static-gray-400'
  | 'static-gray-500'
  | 'static-gray-600'
  | 'static-gray-700'
  | 'static-gray-800'
  | 'static-gray-900'
  | 'static-blue-400'
  | 'static-blue-500'
  | 'static-blue-600'
  | 'static-blue-700'
  | 'static-red-400'
  | 'static-red-500'
  | 'static-red-600'
  | 'static-red-700'
  | 'static-orange-400'
  | 'static-orange-500'
  | 'static-orange-600'
  | 'static-orange-700'
  | 'static-green-400'
  | 'static-green-500'
  | 'static-green-600'
  | 'static-green-700'
  | 'static-celery-400'
  | 'static-celery-500'
  | 'static-celery-600'
  | 'static-celery-700'
  | 'static-chartreuse-400'
  | 'static-chartreuse-500'
  | 'static-chartreuse-600'
  | 'static-chartreuse-700'
  | 'static-yellow-400'
  | 'static-yellow-500'
  | 'static-yellow-600'
  | 'static-yellow-700'
  | 'static-magenta-400'
  | 'static-magenta-500'
  | 'static-magenta-600'
  | 'static-magenta-700'
  | 'static-fuchsia-400'
  | 'static-fuchsia-500'
  | 'static-fuchsia-600'
  | 'static-fuchsia-700'
  | 'static-purple-400'
  | 'static-purple-500'
  | 'static-purple-600'
  | 'static-purple-700'
  | 'static-indigo-400'
  | 'static-indigo-500'
  | 'static-indigo-600'
  | 'static-indigo-700'
  | 'static-seafoam-400'
  | 'static-seafoam-500'
  | 'static-seafoam-600'
  | 'static-seafoam-700'
  | 'negative'
  | 'notice'
  | 'positive'
  | 'informative'

'thin'
  | 'thick'
  | 'thicker'
  | 'thickest'

'default'
  | 'negative'
  | 'notice'
  | 'positive'
  | 'informative'
  | 'hover'
  | 'focus'
  | 'down'
  | 'extralight'
  | 'light'
  | 'mid'
  | 'dark'
  | 'transparent'
  | 'translucent-dark'
  | 'translucent-darker'
  | ColorValue

'xsmall'
  | 'small'
  | 'regular'
  | 'medium'
  | 'large'