Create a Stylable Component Library

We are now experimenting with a new component library based on Stylable and React. It is in the early development stages and will be available soon. Here are some guidelines we gathered related to this project that you may be interested in following if you build your own library.

Stylable enables you to author a component library, that can be themed, and easily consumed and styled, by other Stylable projects.

Stylable is the styling, CSS side of working with components. For the Stylable CSS to be fully useful, it must integrate with a component library from another source, for example React.

As a best practice, we recommend following this folder structure:

src/
    |
    --- components/
    |   |
    |   --- my-component/
    |   |   |
    |   |   my-component.jsx
    |   |   my-component.st.css
    |   |
    |   project.st.css
    |
    --- themes/
    |   |
    |   backoffice-theme.st.css
    |   app-theme.st.css

Note: Although you may think the project file should be at the src level, we recommend you to create the project.st.css file at the same level as your components because there are many links between this file and your component files.

The project.st.css file

As a first step, create a project commons stylesheet named project.st.css in the src/components directory. This exposes the API for the project.

Note: It is recommended to leave the project’s CSS rulesets empty with no declarations. These should be defined in a theme file.

Themable components

Your components should be as easy to style and theme as possible. We recommend following these guidelines when planning:

More best practices for themable components can be found in the Stylable component best practices guide.

In the following code, you can see a component described with:

/* app.st.css */
@namespace "App";
:import {
    -st-from: '../project.st.css';
    -st-named: color1, color2, emphasisBox;
}
.root {
    color: value(color1);
    background: value(color2);
}
.messageBox {
    /* append emphasisBox CSS class to messageBox JS output */
    -st-extends: emphasisBox;
}

Theme

The Stylable library can include multiple theme files that render a different look and feel per theme. A theme imports the project.st.css file as theme to override variables, variants and classes from the library.

In the following code, you can see a theme file customizing the library:

/* backoffice-theme.st.css */
@namespace "backofficeTheme";
:import {
    -st-from: '../project.st.css';
    -st-named: color1, color2, cancelButton, emphasisBox;
    color1: white;
    color2: red;
}
.cancelButton {
    color: value(color1);
    background: value(color2);
}
.emphasisBox {
    border: 3px solid value(color2);
}

Read more about using themes in theme an application.