Renderer

The renderer is the most important utility providing methods to render your styles. It caches every single style that is rendered at any time. Therefore it always has an up-to-date snapshot of your current CSS environment.

You should only have a single renderer which handles all styles of your whole application. To create a new renderer instance, simply use the

createRenderer

method to actually get a renderer instance.

Methods

renderRule

renderKeyframe

renderFont

renderStatic

clear

renderRule

Renders a

rule

using the

props

to resolve it.

Arguments

Argument	Type	Default	Description
rule	Function		A function which satisfies the rule behavior. It must return a valid style object.
props	Object?	`{}`	An object containing properties to resolve dynamic rule values.

Returns

(string): The resolving CSS class name.

Example

import { createRenderer } from 'fela'

const renderer = createRenderer()

const rule = (props) => ({
  backgroundColor: 'red',
  fontSize: props.size,
  color: 'blue',
})

renderer.renderRule(rule, { size: '12px' }) // => a b c
renderer.renderRule(rule) // => a c

Tips & Tricks

To write more advanced and/or simpler rules there are some helpful tips & tricks you might want to know and use:

Optional props

Many rules define CSS declarations that semantically belong together e.g.

alignItems

and

justifyContent

. Still, you might not want to use both every time. Therefore, Fela supports optional props. If a value is not set and thus

undefined

or a string containing

undefined

it is simply removed by default.

const rule = (props) => ({
  justifyContent: props.justify,
  alignItems: props.align,
})

renderer.renderRule(rule, { justify: 'center' }) // => a
// .a{justify-content:center}

Default declarations

Sometimes you do not pass all props required to completely resolve all style declarations, but want to use a default value in order to not produce any invalid CSS markup. You can achieve this in two ways. Either with ECMA2015 default function parameters(new tab) or with the logical OR (

||

) operator.

// default parameters
const rule = ({ color = 'red' } = {}) => ({
  color: color,
})

// OR operator
const rule = (props) => ({
  color: props.color || 'red',
})

rule({ color: 'blue' }) // => { color: 'blue' }
rule({}) // => { color: 'red' }

Conditional values

Some values might only be applied, if a certain condition is fulfilled. Instead of complex and big

if

statements you can use the ternary operator.

const rule = ({ type }) => ({
  color: type === 'error' ? 'red' : 'green',
})

rule({ type: 'error' }) // => { color: 'red' }
rule({}) // => { color: 'green' }

renderKeyframe

Renders a

keyframe

using the

props

to resolve it.

Arguments

Argument	Type	Default	Description
keyframe	Function		A function which satisfies the keyframe behavior. It must return a valid keyframe object.
props	Object?	`{}`	An object containing properties to resolve dynamic keyframe values.

Returns

(string): The resolving animation name.

Example

import { createRenderer } from 'fela'

const renderer = createRenderer()

const keyframe = (props) => ({
  '0%': { color: props.initialColor },
  '33%': { color: 'red' },
  '66%': { color: 'green' },
  '100%': { color: props.initialColor },
})

renderer.renderKeyframe(keyframe, { initialColor: 'blue' }) // => k1
renderer.renderKeyframe(keyframe, { initialColor: 'black' }) // => k2

Tips & Tricks

Be sure to only use animateable properties(new tab). Other properties will be ignored.

Keyframe objects must at least have the steps
```
0%
```
and
```
100%
```
or rather
```
from
```
and
```
to
```
. Otherwise it might not be used at all.

renderFont

Renders a

@font-face

rule using the

family

as reference.

Arguments

Argument Type Description

family string A font family reference which is later required to use this font face.

files

Argument	Type	Description
family	string	A font family reference which is later required to use this font face.
files	string[]	An array of valid source paths. It may either be relative (within your project) or absolute (hosted on an external server). It must have one of the following file extensions: `.woff` , `.woff2` , `.eof` , `.ttf` or `.svg`
properties	Object?	Additional font properties which are `fontVariant` , `fontWeight` , `fontStretch` , `fontStyle` and `unicodeRange` .

string[]

An array of valid source paths. It may either be relative (within your project) or absolute (hosted on an external server).
It must have one of the following file extensions:

.woff

.woff2

.eof

.ttf

.svg

properties

Object?

Additional font properties which are

fontVariant

fontWeight

fontStretch

fontStyle

and

unicodeRange

Returns

(string) The font family reference that was passed in.

Example

import { createRenderer } from 'fela'

const renderer = createRenderer()

const files = ['../fonts/Lato.ttf', '../fonts/Lato.woff', '../fonts/Lato.eof']

renderer.renderFont('Lato', files, { fontWeight: 300 })

Caveats

If you are using relative paths such as
```
../fonts/Lato.ttf
```
, keep in mind that it is relative to your
```
index.html
```
.

renderStatic

Renders static styles.

Arguments

Argument Type Description

style string
Object Either a pure CSS string or an object of style declarations.

selector

Argument	Type	Description
style	string Object	Either a pure CSS string or an object of style declarations.
selector	string	If `style` is passed as an object you must specify a `selector` selector.
props	Object?	An object of props that is passed to the plugins processing the style objects.

string

style

is passed as an object you must specify a

selector

selector.

props Object? An object of props that is passed to the plugins processing the style objects.

Example

import { createRenderer } from 'fela'

const renderer = createRenderer()

// string type style
renderer
  .renderStatic('html,body{box-sizing:border-box;margin:0}')
  // object type style
  .renderer.renderStatic(
    {
      boxSizing: 'border-box',
      margin: 0,
    },
    'html,body'
  )

Tips & Tricks

Only use static styles for global CSS rules such as resets.

Use string styles to include legacy and third-party CSS.

Pro Tip

You can even reuse existing formatted CSS using ECMAScript 2015(new tab) template strings(new tab).

import { createRenderer } from 'fela'

const renderer = createRenderer()

renderer.renderStatic(`
html, body {
  box-sizing: border-box;
  margin: 0
}

div {
  display: -webkit-flex;
  display: -moz-flex;
  display: flex
}
`)

Adds a change

listener

to get notified when changes happen.

Argument Type Description

listener

Argument	Type	Description
listener	Function	A callback function that is called on every change. It passes a change object containing information on what actually got rendered or changed. Every change object at least has a unique `type` and optionally some meta data. In addition it passes the `renderer` that triggered the change.

Function

A callback function that is called on every change. It passes a change object containing information on what actually got rendered or changed. Every change object at least has a unique

type

and optionally some meta data. In addition it passes the

renderer

that triggered the change.

(Object): An object containing the corresponding

unsubscribe

-method.

import { createRenderer } from 'fela'

const renderer = createRenderer()

const rule = (props) => ({
  fontSize: props.fontSize,
  color: 'blue',
})

const subscription = renderer.subscribe(console.log)
renderer.renderRule(rule, { fontSize: '12px ' })
// { type: 'rule', style: 'font-size:12px', selector: 'a', media: '' }
// { type: 'rule', style: 'color:blue', selector: 'b', media: '' }

// Unsubscribing removes the event listener
subscription.unsubscribe()

clear

Clears the whole cache and updates the DOM node to remove all CSS rules.