Adding New Utilities

Extend xstyled with your own utilities.

xstyled presents a large collection of utilities to style a complete website. It also exposes a powerful API to be able to create your own utilities.

Configure xstyled

Create your config file

To configure xstyled, create a xstyled.config.js file (.ts works too) and import the createCss function.

// xstyled.config.js import { createCss } from '@xstyled/...'

This function accepts a utility (also called generator) and returns a set of functions to style your application.

// xstyled.config.js import { createCss, system } from '@xstyled/...' export const { css, styled, x, createGlobalStyle } = createCss(system)

system includes all xstyled built-in utilities that you can find in documentation.

Create a custom utility

Let's say you want be able to use a new property not already exposed by xstyled, for example border-inline.

style function let you create the property:

// utilities/border-inline.js import { style } from '@xstyled/...' export const borderInline = style({ prop: 'borderInline', })

Add custom utility to your config file

compose let you compose utilities, by composing system you extend the base xstyled. You can also restrict to a smaller set of utilities if you want.

import { createCss, system, compose } from '@xstyled/...' import { borderInline } from './utilities/border-inline' export const { css, styled, x, createGlobalStyle } = createCss( compose(system, borderInline), )

Utility API

Use a custom prop

By default prop defines both the utility prop and the CSS property generated by the utility. You may want to use another prop, a shortname or something more explicit.

The css option let you distinct the prop from the CSS property.

import { style } from '@xstyled/...' export const borderInline = style({ prop: 'bi', css: 'borderInline' }) // Usage <x.div bi="1px dotted blue" />

Alias property

prop accepts a string or an array of strings. It makes it easy to create aliases like margin and m.

import { style } from '@xstyled/...' export const margin = style({ prop: ['margin', 'm'], css: 'margin', }) // Usage <x.div m={1} /> // or <x.div margin={1} />

Bind property to a primitive

If your property is define by a unit or by a primitive, you should bind it to the primitive. To do that, you have to specify themeGet:

import { style, getColor } from '@xstyled/...' export const borderInlineColor = style({ prop: 'borderInlineColor', themeGet: getColor, }) // Usage <y.div borderInlineColor="red-500" />

Available primitives: getAngle, getAnimation, getBorderColor, getBorderStyle, getBorderWidth, getBorder, getColor, getDuration, getFontSize, getFontWeight, getFont, getInset, getLetterSpacing, getLineHeight, getPercent, getPx, getRadius, getRingWidth, getShadow, getSize, getSpace, getTimingFunction, getTransform, getTransitionProperty, getTransition and getZIndex.

Multi CSS properties

css accepts a string or an array of strings. It let you create properties like px.

import { style } from '@xstyled/...' export const px = style({ prop: ['px'], css: ['paddingTop', 'paddingBottom'], })

Generate arbitrary style

Specify a function in css to define arbitrary style. It makes it easy to create advanced utility like clearfix.

import { style } from '@xstyled/...' export const clearfix = style({ prop: 'clearfix', css: () => ({ '&::after': { display: 'block', content: '', clear: 'both', }, }), })
Edit this page on GitHub