Skip to content

Overriding styles with the sx prop

Our goal with Primer Components is to hit the sweet spot between providing too little and too much styling flexibility; too little and the design system is too rigid, and too much and it becomes too difficult to maintain a consistent style. Our components already support a standard set of system props, but sometimes a component just isn't quite flexible enough to look the way you need it to look. For those cases, we provide the sx prop.

The sx prop allows ad-hoc styling that is still theme aware. Declare the styles you want to apply in camel-cased object notation, and try to use theme values in appropriate CSS properties when possible. If you've passed a custom theme using ThemeProvider or a theme prop, the sx prop will honor the custom theme. For more information on theming in Primer Components, check out the Primer Theme documentation.

When to use the sx prop

The sx prop provides a lot of power, which means it is an easy tool to abuse. To best make use of it, we recommend following these guidelines:

  • Use the sx prop for small stylistic changes to components. For more substantial changes, consider abstracting your style changes into your own wrapper component.
  • Use system props instead of the sx prop whenever possible.
  • Avoid nesting and pseudo-selectors in sx prop values when possible.

Basic example

This example demonstrates applying a bottom border to Heading, a component that does not receive BORDER system props. The borderBottomWidth value comes from theme.borderWidths and borderBottomColor comes from theme.colors.

Heading

Heading with bottom border

Responsive values

Just like values passed to system props, values in the sx prop can be provided as arrays to provide responsive styling.

Responsive background color

Nesting, pseudo-classes, and pseudo-elements

The sx prop also allows for declaring styles based on media queries, psueudo-classes, and pseudo-elements. This example, though contrived, demonstrates the ability:

First
Second
Third
Edit this page on GitHub
1 contributorBinaryMuse
Last edited by BinaryMuse on April 27, 2020