/fela

State-Driven Styling in JavaScript

Primary LanguageJavaScriptMIT LicenseMIT

Fela

Fela is a small, high-performant and framework-agnostic toolbelt to handle state-driven styling in JavaScript.
It is dynamic by design and renders your styles depending on your application state.

It generates atomic CSS and supports all common CSS features such as media queries, pseudo classes, keyframes and font-faces. Fela ships with a powerful plugin API adding e.g. vendor prefixing or fallback value support.

Fela can be used with React or with any other view library. It even supports React Native.

TravisCI Test Coverage npm downloads gzipped size Gitter Backers on Open Collective Sponsors on Open Collective

Support Us

Support Robin Frischmann's work on Fela and its ecosystem directly via Patreon.

Or support us on Open Collective to fund community work.
Thank you to all our backers!

Installation

yarn add fela

You may alternatively use npm i --save fela.

Features

  • Dynamic styling
  • High performance
  • Scoped atomic CSS
  • Dead code elimination
  • Framework-agnostic
  • Universal rendering
  • Many CSS features
  • Huge ecosystem
  • Vendor prefixing
  • Component theming
  • Local namespace

The Gist

Fela's core principle is to consider style as a function of state.
The whole API and all plugins and bindings are built on that idea.
It is reactive and auto-updates once registered to the DOM.

The following example illustrates the key parts of Fela though it only shows the very basics.

import { createRenderer } from 'fela'

// a simple style rule is a pure function of state
// that returns an object of style declarations
const rule = state => ({
  textAlign: 'center',
  padding: '5px 10px',
  // directly use the state to compute style values
  background: state.primary ? 'green' : 'blue',
  fontSize: '18pt',
  borderRadius: 5,
  // deeply nest media queries and pseudo classes
  ':hover': {
    background: state.primary ? 'chartreuse' : 'dodgerblue',
    boxShadow: '0 0 2px rgb(70, 70, 70)'
  }
})


const renderer = createRenderer()

// fela generates atomic CSS classes in order to achieve
// maximal style reuse and minimal CSS output
const className = renderer.renderRule(rule, { 
  primary: true
}) // =>  a b c d e f g

The generated CSS output would look like this:

.a { text-align: center }
.b { padding: 5px 10px }
.c { background: green }
.d { font-size: 18pt }
.e { border-radius: 5px }
.f:hover { background-color: chartreuse }
.g:hover { box-shadow: 0 0 2px rgb(70, 70, 70) }

Primitive Components

If you're using Fela, you're most likely also using React.
Using the React bindings, you get powerful APIs to create primitive components.
If you ever used styled-components, this will look very familiar.

Read: Usage with React for a full guide.

import { createComponent, Provider } from 'react-fela'
import { render } from 'react-dom'

const rule = state => ({
  textAlign: 'center',
  padding: '5px 10px',
  background: state.primary ? 'green' : 'blue',
  fontSize: '18pt',
  borderRadius: 5,
  ':hover': {
    background: state.primary ? 'chartreuse' : 'dodgerblue',
    boxShadow: '0 0 2px rgb(70, 70, 70)'
  }
})

const Button = createComponent(rule, 'button')

render(
  <Provider renderer={renderer}>
    <Button primary>Primary</Button>
    <Button>Default</Button>
  </Provider>,
  document.body
)

Examples

Documentation

Workshop

If you are coming from CSS and want to learn JavaScript Styling with Fela, there is a full-feature fela-workshop which demonstrates typical Fela use cases. It teaches all important parts, step by step with simple examples. If you already know other CSS in JS solutions and are just switching to Fela, you might not need to do the whole workshop, but it still provides useful information to get started quickly.

Posts & Talks

Ecosystem

There are tons of useful packages maintained within this repository including plugins, enhancers, bindings and tools that can be used together with Fela. Check the Ecosystem documentation for a quick overview.

Community

Apart from all the packages managed within this repository, there are many community third-party projects that are worth mentioning:

  • aesthetic - React style and theme layer with Fela support
  • base-styling-components - Abstract Box and Text Components
  • catstack - A modular mad science framework for teams working on production web apps
  • cf-ui - Cloudflare UI Framework
  • cycle-fela - Cycle bindings for Fela
  • dogstack - A popular-choice grab-bag framework for teams working on production web apps
  • este - Starter kit for universal full–fledged React apps build with Fela
  • fela-components - Styling library for React and Fela
  • fela-react-prop - Generate class names for fela style rule and apply them as property on a wrapped component
  • fela-styles-connector - Simplified react-fela connect with auto-bound styles
  • frejya: Pass styles as props to components
  • hyper-fela - HyperScript bindings for Fela
  • kilvin - Primitive React Layout Components with Fela
  • storybook-addon-props-fela: Document the props of your Fela components in storybook.
  • telaviv - React Universal Rendering
  • vashet - ClojureScript wrapper for Fela
  • veel - Base react styling components using fela with a design system
  • vue-fela - Vue bindings for Fela

Support

Got a question? Come and join us on Gitter!
We'd love to help out. We also highly appreciate any feedback.

Who's using Fela?

Your company is using Fela, but is not listed yet? Add your company / organisation

Contributing

This project exists thanks to all the people who contribute.

We highly appreciate any contribution.
For more information follow the contribution guide.
Also, please read our code of conduct.

License

Fela is licensed under the MIT License.
Documentation is licensed under Creative Common License.
Created with ♥ by @rofrischmann and all the great contributors.

Sponsor