API

Engine#

`RenderOptions`#

Most render methods support the following options. Read the documentation on options for more information.

deterministic (boolean) - Generate class names using a deterministic hash (c1sjakp) instead of an auto-incremented value (a1). Useful for scenarios like unit tests. Defaults to false.
direction (ltr | rtl) - Convert and swap LTR (left-to-right) based declarations to RTL (right-to-left).
media (string) - A media query to wrap the declaration with (without @media).
rankings (object) - An empty object to use for specificity ranking cache lookups. Useful for ensuring the correct specificity when order of declarations change.
selector (string) - A CSS selector to scope the declaration within. This is handled automatically when using rules.
supports (string) - A feature query to wrap the declaration with (without @supports).
unit (string) - A unit to append to numerical values. Defaults to px.
vendor (boolean) - Apply vendor prefixes to properties and values that require it. We prefix features for browsers with >= 1% market share. Defaults to false.

`setRootVariables`#

Engine#setRootVariables(vars: CSSVariables): void

Applies CSS variables to the document :root. Variable names can be defined in camel-case or standard variable format (leading --).

engine.setRootVariables({
    '--font-color': 'black',
    backgroundColor: 'white',
});

`renderDeclaration`#

Engine#renderDeclaration\<K extends Property>(property: K, value: Properties[K], options?: RenderOptions): ClassName

Renders a property-value pair, known as a CSS declaration, and returns a CSS class name. Will return the same class name for the same property-value pair.

const className = engine.renderDeclaration('display', 'block'); // -> a

.a {
    display: block;
}

Declarations can also be scoped within a selector (pseudo, attribute, etc) by using the selector option.

const className = engine.renderDeclaration('display', 'block', { selector: ':hover' }); // -> b

.b:hover {
    display: block;
}

`renderRule`#

Engine#renderRule(properties: Rule, options?: RenderOptions): ClassName

Renders a collection of property-value pairs, known as a CSS rule (or ruleset), and returns a CSS class name for each declaration. A collection of declarations is known as a style object. It returns an object with a result (the class name), and variants (array of class names).

const className = engine.renderRule({
    display: 'block',
    textAlign: 'center',
    background: 'transparent',
});

className.result; // -> a b c
className.variants; // []

.a {
    display: block;
}
.b {
    text-align: center;
}
.c {
    background: transparent;
}

Rules can also infinitely render nested @media queries, @supports queries, pseudo classes and elements, attributes, combinators, and other selectors, by declaring nested style objects.

const className = engine.renderRule({
    display: 'block',
    background: 'gray',

    ':hover': {
        background: 'black',
    },

    '@media': {
        '(max-width: 300px)': {
            display: 'inline-block',
        },
    },
});

`renderRuleGrouped`#

Engine#renderRuleGrouped(properties: Rule, options?: RenderOptions): ClassName

Grouped rules work in a similar fashion to rules, but instead of creating a unique class per declaration (atomic), they group all declarations within a single class (non-atomic). This exists for situations where all styles need to be encapsulated under a single class name, for example, themes.

const className = engine.renderRuleGrouped({
    display: 'block',
    textAlign: 'center',
    background: 'transparent',
});

className.result; // -> a
className.variants; // []

.a {
    display: block;
    text-align: center;
    background: transparent;
}

This method should rarely be used, as it circumvents the performance and filesize gains that the atomic cache provides.

`renderFontFace`#

Engine#renderFontFace(fontFace: FontFace, options?: RenderOptions): string

Renders a font face object as a @font-face at-rule and returns the font family name. If the fontFamily property is not defined, a unique collision-free one will be generated.

const fontFamily = engine.renderFontFace({
    fontFamily: 'Roboto',
    fontStyle: 'normal',
    fontWeight: 800,
    src: 'url("fonts/Roboto.woff2")',
}); // -> Roboto

@font-face {
    /* ... */
}

`renderImport`#

Engine#renderImport(url: string, options?: RenderOptions): void

Renders a CSS file path as an @import at-rule. Only accepts the URL. Use the conditions option to apply media queries.

engine.renderImport({ path: './path/to/file.css', url: true });

@import url('./path/to/file.css');

`renderKeyframes`#

Engine#renderKeyframes(keyframes: Keyframes, name?: string, options?: RenderOptions): string

Renders a keyframes object as a @keyframes at-rule and returns the animation name. A custom animation name may be provided as the 2rd argument (does not account for collision), otherwise a unique collision-free one will be generated.

const animationName = engine.renderKeyframes({
    from: {
        transform: 'translateX(0%)',
    },
    to: {
        transform: 'translateX(100%)',
    },
}); // -> kf18jh28d

@keyframes kf18jh28d {
    /* ... */
}

ServerEngine#

`extractStyles`#

extractStyles<T>(app: T): T

Extracts critical CSS from the application being rendered (without layout HTML) by injecting the current server engine. CSS must then be rendered to style tags.

const app = engine.extractStyles(<App />);

Read the documentation on server-side rendering to utilize this correctly.

Server-side#

`renderToStyleMarkup`#

renderToStyleMarkup(engine: Engine): string

Renders extracted styles into a collection of style tags for hydration. Tags must be included in the HTML response.

const markup = renderToStyleMarkup(engine);

Testing#

`createTestStyleEngine`#

createTestStyleEngine(options?: EngineOptions): Engine

Create a style engine pre-configured for testing.

const engine = createTestStyleEngine();

`getRenderedStyles`#

getRenderedStyles(type: 'global' | 'standard' | 'conditions'): string

Returns all rendered styles as a CSS string for the target <style /> type.

expect(getRenderedStyles('standard')).toMatchSnapshot();

`purgeStyles`#

purgeStyles(type: 'global' | 'standard' | 'conditions'): void

Removes all rendered styles from the target <style /> type. If the type is not provided, it will purge all 3 types.

purgeStyles(); // all
purgeStyles('global');

Engine#

RenderOptions#

setRootVariables#

renderDeclaration#

renderRule#

renderRuleGrouped#

renderFontFace#

renderImport#

renderKeyframes#