Middleware

The ThemeProvider allows you to install middleware. With middleware, you can manipulate the style object right before it's passed to Styletron.

Named colors

We provide a very useful sample middleware on ThemeProvider.middlewares.mapColorKeys. It is installed automatically, although you can remove it (see below). It looks for any color-related style attribute, and translates named keys to CSS colors.

// in your library's meta, or the end-user's global theme, 
// enter the color names and values in meta.colors
//
const ourAppTheme = {
  meta: {
    colors: {
      primary: '#00c653',   // "primary" and "warning" are now color keys
      warning: '#ff3056'
    }
  },
  Button: { /* ... */ },
  Dropdown: { /* ... */ }
};

// in your component, you can use color keys. a color key must still
// be quoted; it's not a variable!
//
const defaultButtonTheme = {
  fontSize: '20px',
  color:    'primary'
};

/*
  the middleware translates the color keys, using the dictionary in theme.meta.colors:

    const defaultButtonTheme = {
      fontSize: '20px',
      color:    '#00c653'
    };
*/

With this middleware installed, you can use any key from theme.meta.colors on any color property, from border-color to -webkit-tap-highlight-color. You can also use color codes in shorthand properties like border. Note that the colors object in the global meta must be flat; you can't nest or group colors.

If you use color keys properly in your components, your users should be easily able to change their theme from light to dark or from blue to green. This requires discipline in avoiding color constants in your components, using only named color keys.

Have a look at the middleware source code for details, or if you want to write your own middleware to handle grouped colors, font sizes, or anything else.

Middleware is applied as the last link in the theme cascade.

Installing middleware

To install middleware, pass an array of functions to your theme provider component. If you omit this prop, we will install the color mapping middleware for you. If you want to remove the default, or add other middleware functions, you must fully specify in the array you pass to the ThemeProvider component. To remove all middleware, pass an empty array.

import {ThemeProvider} from 'styletron-utils';

const ourAppTheme = {/*...*/};

// the provided middleware is exposed here:
const colorKeyMiddleware = ThemeProvider.middlewares.mapColorKeys;

// create an array of middlewares. you can pass an
// empty array to remove the color key mapper, or
// you can add other functions to augment it
//
const ourMiddlewares = [
  colorKeyMiddleware,
  // add your other middleware functions here
];

render(
  <StyletronProvider styletron={new Styletron()}>
    <ThemeProvider theme={ourAppTheme} middlewares={ourMiddlewares}>
      <App />
    </ThemeProvider>
  </StyletronProvider>
, document.getElementById('app'));

This is typically done by the end-user of your library. However, you can bring ownership of middleware into your library by exposing a new provider that manages the middleware. See the sample for library authors.

Creating your own middleware

The signature of a middleware function is:

function middleware(theme, styles) {
  return styles;
}

• theme is the full global theme object
• stylesare the computed instance styles for an element. As with other Styletron objects, this may have nested objects for :focus, media queries, etc.

Your function must not modify either of the input parameters. If you need to modify styles, you must return a new object.