Skip to content
Theme UI


A number of built-in UI components are available for layouts, grids, buttons, form elements, and more. Components can be used as an alternative to the JSX pragma for using Theme UI features, or in parallel to provide specific UI components.


Theme UI components can be customized by adding styles to your theme. Each component accepts a variant prop to quickly change custom stylistic variations that you define.

// ...base theme...
// After the base theme, define the variants:
buttons: {
secondary: {
fontWeight: 'bold',
color: 'white',
bg: 'primary',
'&:hover': {
bg: 'dark',
text: {
caps: {
textTransform: 'uppercase',
letterSpacing: '.2em',
heading: {
fontFamily: 'heading',
fontWeight: 'heading',
lineHeight: 'heading',
display: {
// extends the text.heading styles
variant: 'text.heading',
fontSize: [6, 7, 8],
fontWeight: 'display',
cards: {
primary: {
padding: 2,
borderRadius: 4,
boxShadow: '0 0 4px 1px rgba(0, 0, 0, 0.5)',


All Theme UI components include the following props.

sxObjectTheme-aware styles
variantStringApplies a theme variant style
asStringChanges the underlying HTML element

Style Props

Each Theme UI component includes shorthand props for applying margin, padding, and color styles. These props work the same as properties within the sx prop, but allow for a more terse syntax for readability.

colorForeground color
bgBackground color
margin, mMargin
marginTop, mtMargin Top
marginRight, mrMargin Right
marginBottom, mbMargin Bottom
marginLeft, mlMargin Left
marginX, mxMargin Left & Right
marginY, myMargin Top & Bottom
padding, pPadding
paddingTop, ptPadding Top
paddingRight, prPadding Right
paddingBottom, pbPadding Bottom
paddingLeft, plPadding Left
paddingX, pxPadding Left & Right
paddingY, pyPadding Top & Bottom
Edit the page on GitHub
Linked Headings