Stylable enables you to import other stylesheets and modules in a way that is similar to JS Imports. You can then use the stylesheet or module as it's been defined, or just one or more of its named values, in your own Stylable stylesheet.
Stylable supports two types of import syntax that can be used, the two are identical in their capabilities.
@st-importat-rule directive - A newer more concise syntax, similar to ES imports:
<DEFAULT_NAME>with your desired local name to import an entire stylesheet, representing its root class
- Inside the square brackets, import any inner parts belonging to said stylesheet
:importruleset directive - The original more verbose way of importing symbols, uses the Stylable syntax beginning with
-st-default:Imports the default export of the module named in
-st-from:. Use with the name by which to identify the imported value in the scoped stylesheet.
-st-named:List of the named exports to import into the local scoped stylesheet from the file named in
Every example below will feature both types of import syntaxes, their end result is identical.
:importis a Stylable directive and not a selector.
@st-importis a Stylable directive and not an actual at-rule.
- Import statements cannot be used as a part of a complex selector or inside a CSS ruleset.
- Multiple imports may conflict in their used symbol names; the last one in the file wins.
Here are some examples of how you can use imports in your Stylable stylesheet.
button.st.css stylesheet from a local location. Assign the name
Button to the default export of that stylesheet for use in this scoped stylesheet.
When importing another stylesheet, the default import represents the root of the stylesheet and is generally treated as a component, and named imports represent other internal stylesheet parts.
Generally when importing a default value from a stylable file, you should use a capital letter to signify that the value represents a component root node in this stylesheet.
Named imports from a stylesheet can be used to bring symbols of different types, which you can then use inside your stylesheet.
- Stylable Variables
- CSS Variables
- Keyframes - special case, see importing keyframes entry below
my-mixins.js. These named exports are now imported into this scoped stylesheet.
When importing named values, they are generally used as class or tag selectors and, therefore, you should camelCase to name them.
my-mixins.js. The value
gridMixin is used as is and
tooltipMixin has been renamed for use in this scoped stylesheet as
tooltip. These mixins are referred to as
tooltip in this stylesheet.
In Stylable, both class names and keyframes undergo namespacing to avoid collision. However, despite the two being global, they do not share a namespace in CSS - this means that you can have both a class name and a keyframe with the same name.
Due to this, when importing keyframes from another stylesheet, a special
keyframes() directive needs to be used.
You can read more about keyframes behavior here.