Theming

The theme object is where you define your application's color palette, type scale, font stacks, breakpoints, border-radius values, and more.

ThemeProvider

Import the ThemeProvider from admin-ui to be able to use the default theme and other internal features.

// 1. import the ThemeProvider
import { ThemeProvider } from '@vtex/admin-ui'

function RootComponent() {
  // 2. Use at the root of your app
  return <ThemeProvider>{/** your app code here */}</ThemeProvider>
}

Csx

Use the csx function to style native JSX elements by creating a className with the styles. The styles are defined through the StyleObject param. This function always use the default theme under the hood.

// import the csx function
import { csx } from '@vtex/admin-ui'

function Example() {
  return (
    <nav
      className={csx({
        bg: '$primary',
        'button + button': {
          marginLeft: '$s',
        },
      })}
    />
  )
}

Overriding

Theme

The ThemeProvider provides a prop called experimentalTheme for thoses cases when you need to override the default theme and meet some specific design requirements. The experimentalTheme prop will receive the new theme object.

function RootComponent() {
  const customTheme = {
    colors: {
      // all colors styles
    },
    fonts: {
      // all font styles
    },
    // other theme props...
  }

  // Use at the root of your app
  return (
    <ThemeProvider experimentalTheme={customTheme}>
      {/** your app code here */}
    </ThemeProvider>
  )
}

info

When you override the default theme and you still want to style native JSX elements, instead of using the csx function, as shown earlier, you should use the cn function, because the csx function only uses the default theme.

Global

The ThemeProvider provides boolean a prop called experimentalDisabledGlobalStyles to disable all the default global styles and enabling the use of your own global styles.

function RootComponent() {
  // Use at the root of your app
  return (
    <ThemeProvider experimentalDisabledGlobalStyles>
      {/** your app code here */}
    </ThemeProvider>
  )
}

Colors

Color themes are used to reflect a product's style with consistency across all components used on the application. Each color has some specific function when applied to an element on the screen. They can be customized to match the app's style guidelines, reflecting their function.

Our design system provides an accessible default palette to get you up and running. To check how we use them semantically, you can check the Design Tokens section

Typography

The StyleObject accepts the text prop. It combines fontFamily, fontSize, fontVariationSettings, and lineHeight css properties for a consistent font rendering throught the product.

Loading...

Value	Description
$pageTitle	Page header title
$title1	Primary titles
$title2	Nested titles
$action1	Actions text
$action2	Less proeminent actions, such as menus
$display	Totalizer value
$body	Text in tables, modals, toasts, alerts, cards; Text in form fields and controls; Placeholder text in form fields.
$detail	Text in tag, tooltip and table pagination; Form error and help text. Labels in form field placeholders and select inline.

Breakpoints

Our styleguide comes with a predefined set of commonly used breakpoints. Detailed info about Responsive Design

export default {
  breakpoints: {
    mobile: '640px',
    tablet: '768px',
    desktop: '1024px',
    widescreen: '1280px',
  },
}

Spacing

The space key allows you to customize the global spacing and sizing scale for your project. By default these spacing values can be referenced by the padding, margin, and top, left, right, bottom styles.

Multiple Properties: Combines two or more CSS properties into one.

Property	Combines	Description
paddingX	paddingLeft, paddingRight	Horizontal padding
paddingY	paddingTop, paddingBottom	Vertical padding
marginX	marginLeft, marginRight	Horizontal margin
marginY	marginTop, marginBottom	Vertical margin

export default {
  space: {
    0: '0rem',
    1: '0.25rem',
    2: '0.5rem',
    3: '0.75rem',
    4: '1rem',
    5: '1.25rem',
    6: '1.5rem',
    7: '1.75rem',
    8: '2rem',
    px: '0.0625rem',
    '2px': '0.125rem',
  },
}

The values are proportional, so 1 spacing unit is equal to 0.25rem, which translates to 4px by default in common browsers.

tip

Mental model: If you need a spacing of 24px, divide it by 4. That'll give you 6. Then use it in your component.

Token	rem	Pixels	size
0	0rem	0px
px	0.0625rem	1px
2px	0.125rem	2px
1	0.25rem	4px
2	0.5rem	8px
3	0.75rem	12px
4	1rem	16px
5	1.25rem	20px
6	1.50rem	24px
7	1.75rem	28px
8	2rem	32px

Sizes

The sizes key allows you to customize the global sizing of components you build for your project. By default these sizes value can be referenced by the width, height, and maxWidth, minWidth, maxHeight, minHeight styles.

Multiple Properties: Combines two or more CSS properties into one.

Property	Combines	Description
size	width, height	Element size, useful to create a square or perfect circle

export default {
  sizes: {
    sm: '20rem',
    md: '48rem',
    lg: '56rem',
    xl: '64rem',
    '1/2': '50%',
    '1/4': '25%',
    '2/4': '50%',
    '3/4': '75%',
    '1/8': '12.5%',
    '2/8': '25%',
    '3/8': '37.5%',
    '4/8': '50%',
    '5/8': '62.5%',
    '6/8': '75%',
    '7/8': '87.5%',
    '1/12': '8.333333%',
    '2/12': '16.666667%',
    '3/12': '25%',
    '4/12': '33.333333%',
    '5/12': '41.666667%',
    '6/12': '50%',
    '7/12': '58.333333%',
    '8/12': '66.666667%',
    '9/12': '75%',
    '10/12': '83.333333%',
    '11/12': '91.666667%',
    full: '100%',
    screenHeight: '100vh',
    screenWidth: '100vw',
  },
}

Border Radius

Our styleguide comes with a set of smooth corner radius values.

export default {
  borderRadius: {
    default: '4px',
    flat: '0px',
    pill: '100px',
    circle: '100%',
  },
}

Border Variant

The StyleObject accepts the border prop. It is a shortcut for the border variants of the admin-ui.

Loading...

Value	Description
default	the most common border-style used along with all the admin
divider-bottom	add a border dividing the current element with the one below it
divider-top	add a border dividing the current element with the one above it

export default {
  border: {
    default: {
      borderWidth: '1px',
      borderStyle: 'solid',
      borderRadius: 'default',
      borderColor: 'mid.tertiary',
    },
    'divider-bottom': {
      borderBottomWidth: '1px',
      borderBottomStyle: 'solid',
      borderBottomLeftRadius: 0,
      borderBottomRightRadius: 0,
      borderColor: 'mid.tertiary',
    },
    'divider-top': {
      borderTopWidth: '1px',
      borderTopStyle: 'solid',
      borderTopLeftRadius: 0,
      borderTopRightRadius: 0,
      borderColor: 'mid.tertiary',
    },
  },
}