API
#
EngineRenderOptions
#
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 tofalse
.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 topx
.vendor
(boolean
) - Apply vendor prefixes to properties and values that require it. We prefix features for browsers with >= 1% market share. Defaults tofalse
.
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 --
).
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.
Declarations can also be scoped within a selector (pseudo, attribute, etc) by using the selector
option.
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).
Rules can also infinitely render nested @media
queries, @supports
queries, pseudo classes and
elements, attributes, combinators, and other selectors, by declaring nested style objects.
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.
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.
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.
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.
#
ServerEngineextractStyles
#
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.
Read the documentation on server-side rendering to utilize this correctly.
#
Server-siderenderToStyleMarkup
#
renderToStyleMarkup(engine: Engine): string
Renders extracted styles into a collection of style
tags for
hydration. Tags must be included in the HTML response.
#
TestingcreateTestStyleEngine
#
createTestStyleEngine(options?: EngineOptions): Engine
Create a style engine pre-configured for testing.
getRenderedStyles
#
getRenderedStyles(type: 'global' | 'standard' | 'conditions'): string
Returns all rendered styles as a CSS string for the target <style />
type.
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.