This library is still in development and is available only for internal usage at VTEX.
Skip to main content

Developing

Theming

Version: Next

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...
ValueDescription
$pageTitlePage header title
$title1Primary titles
$title2Nested titles
$action1Actions text
$action2Less proeminent actions, such as menus
$displayTotalizer value
$bodyText in tables, modals, toasts, alerts, cards; Text in form fields and controls; Placeholder text in form fields.
$detailText 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.

PropertyCombinesDescription
paddingXpaddingLeft, paddingRightHorizontal padding
paddingYpaddingTop, paddingBottomVertical padding
marginXmarginLeft, marginRightHorizontal margin
marginYmarginTop, marginBottomVertical 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.

TokenremPixelssize
00rem0px
px0.0625rem1px
2px0.125rem2px
10.25rem4px
20.5rem8px
30.75rem12px
41rem16px
51.25rem20px
61.50rem24px
71.75rem28px
82rem32px

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.

PropertyCombinesDescription
sizewidth, heightElement 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...
ValueDescription
defaultthe most common border-style used along with all the admin
divider-bottomadd a border dividing the current element with the one below it
divider-topadd 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',
},
},
}