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',
    },
  }),
})