React Spectrum
DocsReleasesBlog
React Spectrum

Style Macro

The style macro supports a constrained set of values per property that conform to Spectrum 2.

Colors

All Spectrum 2 color tokens are available across color properties (e.g., backgroundColor, color, borderColor).

Dimensions

Text

Spectrum 2 typography can be applied via the font shorthand, which sets fontFamily, fontSize, fontWeight, lineHeight, and color. You can override any of these individually. Note that font should be applied on a per element basis rather than globally so as to properly conform with Spectrum designs.

<main>
  <h1 className={style({font: 'heading-xl'})}>Heading</h1>
  <p className={style({font: 'body'})}>Body</p>
  <ul className={style({font: 'body-sm', fontWeight: 'bold'})}>
    <li>List item</li>
  </ul>
</main>

Effects

Layout

Misc

Conditions

Utilities

The style macro system provides built-in utility functions for common patterns.

baseColor

Returns a set of stateful color token references for the default, hovered, focus-visible, and pressed states of a component.

import {baseColor, style} from '@react-spectrum/s2/style' with {type: 'macro'};

const styles = style({
  backgroundColor: baseColor('gray-100')
});

color

Resolves a Spectrum color token name to a CSS color value string. Supports opacity modifiers via the color/opacity syntax.

import {color, style} from '@react-spectrum/s2/style' with {type: 'macro'};

const styles = style({
  color: color('gray-800'),
  borderColor: color('accent-900/50')
});

lightDark

Produces a light-dark() CSS color value that resolves to different colors depending on the current color scheme.

import {lightDark, style} from '@react-spectrum/s2/style' with {type: 'macro'};

const styles = style({
  backgroundColor: lightDark('gray-25', 'gray-900')
});

colorMix

Mixes two Spectrum colors by a given percentage using CSS color-mix() in sRGB color space.

import {colorMix, style} from '@react-spectrum/s2/style' with {type: 'macro'};

const styles = style({
  backgroundColor: colorMix('accent-900', 'gray-25', 50)
});

size

Converts a pixel value to a scalable CSS size expression using the Spectrum 2 scale factor. The result is a calc() expression that multiplies the rem-converted value by the current scale factor. The scale factor differs between touch and non-touch devices.

import {size, style} from '@react-spectrum/s2/style' with {type: 'macro'};

const styles = style({
  width: size(200),
  height: size(48)
});

space

Converts a pixel value to a Spectrum spacing token in rem units.

import {space, style} from '@react-spectrum/s2/style' with {type: 'macro'};

const styles = style({
  gap: space(12) // 12/16 = 0.75rem
});

fontRelative

Converts a pixel value to a font-relative em length. Useful for sizing elements relative to the current font size. Defaults to a 14px base.

import {fontRelative, style} from '@react-spectrum/s2/style' with {type: 'macro'};

const styles = style({
  gap: fontRelative(2)  // 2/14 = ~0.143em
});

focusRing

Returns consistent Spectrum focus ring outline styles for interactive components.

import {focusRing, style} from '@react-spectrum/s2/style' with {type: 'macro'};

const styles = style({
  ...focusRing(),
  borderRadius: 'lg'
});

iconStyle

Generates styles for an icon element with the given size, color, and layout options. Must be imported with {type: 'macro'}.

import {iconStyle} from '@react-spectrum/s2/style' with {type: 'macro'};
import Edit from '@react-spectrum/s2/icons/Edit';

<Edit styles={iconStyle({size: 'XL', color: 'positive'})} />

See the Icons page for more information.

css

Injects a raw CSS string into the style system. The CSS is wrapped in a generated class name and placed within the specified @layer. Returns the generated class name. This is an escape hatch for advanced cases (e.g. pseudo selectors or features not yet available in the style macro API), and should be used sparingly. Must be imported with {type: 'macro'}.

import {css} from '@react-spectrum/s2/style' with {type: 'macro'};

const styles = css(`
  backdrop-filter: blur(8px);
`);

mergeStyles

Merges multiple style strings together, combining the CSS properties from each. Later styles take precedence over earlier ones for the same property. Useful for composing styles from multiple style() macro calls.

import {mergeStyles} from '@react-spectrum/s2';
import {style} from '@react-spectrum/s2/style' with {type: 'macro'};

const baseStyles = style({padding: 8});
const overrideStyles = style({padding: 16, color: 'heading'});
const merged = mergeStyles(baseStyles, overrideStyles);
// merged has `padding: 16` and `color: heading`.

centerPadding

Calculates vertical padding to center a single line of text within a container. Uses the CSS self() function and 1lh unit to compute the padding based on the container's minimum height and border widths. This is useful for precise vertical centering without introducing a flex/grid layout to the container.

import {centerPadding, style} from '@react-spectrum/s2/style' with {type: 'macro'};

const styles = style({
  paddingY: centerPadding()
});

setColorScheme

Returns style properties that set the CSS color-scheme for a component. Defaults to the page's color scheme and supports 'light', 'dark', and 'light dark' values via the colorScheme render prop condition. Intended for root containers (e.g. providers, modals, and popovers), and not needed for individual components.

import {setColorScheme, style} from '@react-spectrum/s2/style' with {type: 'macro'};

const styles = style({
  ...setColorScheme(),
  backgroundColor: 'layer-1'
});