5.0.1 • Published 5 years ago

@anomen/rethemeable v5.0.1

Weekly downloads
Last release
5 years ago


Rethemeable provides utilities for producing and consuming themeable React components.

It doesn't define the notion of theme. A theme can be a list of CSS class names or a set of inline style directives.

It doesn't define how components apply themes. It is up to component to decide what and when to apply CSS class names or inline styles.

Instead Rethemeable define a way to propagate theme through React component tree.

It's up to component authors to declare the theming contract for each component.

It's up to consumers to fulfil the theming contract for each component.


Install from npm:

% npm install rethemeable


Define a themeable component:

import { themeable } from 'rethemeable'
import React from 'react'

class Button extends React.Component {

  render() {
    let theme = this.theme
    return (
      <button className={theme.self}>
        <i className={theme.icon} />

Now define a theme as a collection of styles for a set of React components. Styles for each component are isolated by an unique key within the theme:

import Button from 'widgets/Button'

let BootstrapTheme = {
  [Button.theme]: {
    self: 'btn btn-xs'

And configure it via <ApplyTheme /> component:

import { ApplyTheme } from 'rethemeable'
import React from 'react'

  <ApplyTheme theme={BootstrapTheme}>
      <h1>This is an app</h1>
      <Button>See, I don't have theme prop passed explicitly</Button>

Component <Button /> will receive theme implicitly.

You can also pass theme directly to component via props if you need a more fine-grained control:

<Button theme={BootstrapTheme} />

If you don't want to use <ApplyTheme /> component but just apply some theme on a themeable component you can use theme function:

import { theme } from 'rethemeable'
import ThemeableButton from 'third-party-themeable-button'

let MyButton = theme(ThemeableButton, BootstrapTheme);

React.render(<MyButton>Hello, I'm themed!</MyButton>)

Rethemeable with CSS modules

Rethemeable approach works well with CSS modules, as you can compose your theme from a set of CSS modules:

import Button from 'widgets/Button'
import Modal from 'widgets/Button'

import ButtonTheme from './Button.css'
import ModalTheme from './Modal.css'

let Theme = {
  [Button.theme]: ButtonTheme,
  [ModalTheme.theme]: ModalTheme

Chunking theme and component separately, or when to pass themeKeys

It can be desirable to chunk (or split) bundled assets in production, especially when dealing with larger sites.

When chunking themeable components, the theme and themeable components must to be able to be loaded independently in order for a build pipeline (like Webpack) to properly optimize chunk size and contents.

Separating the definition of theme keys from a given themeable component allows the keys, theme, and components to be loaded if and whenever they are needed.


/** List of theme keys to connect classmaps with component themes */

export {
  Button: Symbol('Button'),
  Modal: Symbol('Modal')


/** Map themeKey Symbols to theme classmaps */

import { Button, Modal } from './key-registry';
import ButtonTheme from './button.css';
import ModalTheme from 'some-module/with-modal-styles.css';

const theme = {
  [Button]: ButtonTheme,
  [Modal]: ModalTheme

export { theme }


import { themeable } from 'rethemeable';
import { compAKey as themeKey } from './key-registry';

class Button {}

export default themeable(Button, {themeKey});


import { themeable } from 'rethemeable';
import { compBKey as themeKey } from './key-registry';

class Modal {}

export default themeable(Modal, {themeKey});


/** Provide theme to themeable components via context */

import Helmet from 'react-helmet';
import { theme } from './theme.js';
import { ApplyTheme } from 'rethemeable';

// map of asset paths extracted during build
import assets from 'assets-map.json';

class App {

    <ApplyTheme theme={theme}>
      <Helmet link={assets.theme.css} />

Without chunks, all components are hard dependencies of a theme. Therefore they must be chunked together to preserve the link of Symbol to theme. This can result bloated chunks and/or tedious maintenance of themes.


5 years ago