Styletron Themer

This is a component-building tool for developers using React and Styletron. With Styletron Themer, you can build a library of components ready for theming and reuse. It builds on the official styletron-react package.

In fact, if you're only building components for a single app, you probably can use styletron-react instead of this library. However, if you'll be building components for use in multiple apps, or if you'll be sharing your components outside your company, this tool might be a good fit.

Design goals

There are two different types of people who will use this tool: component builders and component users. While those roles are often held by the same person (or team), Styletron Themer enables a team of developers to build a set of components ready to be used by other teams in your organization, or other organizations, each with different theming needs.

Our concern with this library is primarily with creating a fabulous experience for component users. A component builder has to work a little harder (not much!) in order to provide users an optimal experience.

We wanted component users to be able to:

• Install a new theme, which overrides base styles for every instance of each component. Want all buttons to have rounded corners? No problem.

• Easily override styles for a single instance of a component, in a way that integrates with the underlying Styletron sub-system. Want this button to be pink? We won't judge.

• Pass attributes down through the component to the underlying HTML element, for things like data- or aria- attributes, id, etc.

We wanted component authors to be able to:

• Define the base theme for each component, including props-dependent adjustments

• Keep styling logic separate from lifecycle or interaction logic. This keeps your component code clean, and also makes styling functions easy to test. Additionally, it makes it easier to share styling logic when we rewrite components in another framework.

• And of course, enable component users to do their work easily, including all of the above goals. They should be able to use, compose, and override your components without friction.

In use

So, since our goals lean towards component users, here is how your components might be used.

function renderComponents() {
  return (
    // Basic Dot
    <Dot />

    // with inline styles (the style is integrated with Styletron)
    <Dot style={{background: 'blue'}} />

    // with props (the component needs to respond to this prop, of course)
    <Dot color="green" />

    // and a new theme, to change the look of ALL basic dots
    <ThemeProvider theme={orangeTheme}>

      // a new orange dot
      <Dot />

    </ThemeProvider>
  );
}

The simplest example

Without explanation or defense, here is a trivial example. This is not well-constructed, just a quick introduction to get you oriented:

const staticStyle  = {background: 'red', borderRadius: '50%},
      dynamicStyle = ({props}) => {background: props.color || 'red'};

class Dot extends React.Component {
  render() {
    <Styled
      staticStyle  = {staticStyle}
      dynamicStyle = {dynamicStyle}
      {...this.props}
    >
      {className => <div className={className} />}
    </Styled>
  }
}

What just happened?

• A staticStyle object was created to hold the default design for the component. You might consider this the base theme for the component.
• A dynamicStyle function (of props) was created to adapt the default design. This function is also part of the component's theme, of course.
• The <Styled> component was rendered. This is where the magic happens. It invokes our render callback with a className parameter, which contains all of the Styletron classes for this element. We then attach those classes to our div.

Read through a more realistic sample component to understand how to use the library. (And learn how to use it well! The above example has several flaws that we overlooked in order present a simple starting point.)

You might also want to read about the theme cascade for details on how styles are merged from the base theme, the user's theme, and any instance-specific and prop-dependent styles.