You use custom selectors to define an alias that can match complex selectors.
For example, a specific type of button within a form that appears only when hovered can be defined as a custom selector. By defining the button as a custom selector with its own name, the button is exposed in the API and available for use by using just the custom selector name.
You could also use custom selectors to define a group of selectors with one name. For example, you can access all the headings on a page as one custom selector. This could be useful if you want to style just their color the same.
The following code maps the alias name
controlBtn that matches any
.btn CSS class nested under the
.controls CSS class.
Custom selectors generate a pseudo-element. So, for example, importing a stylesheet into another stylesheet enables access to the
controlBtn pseudo-element. In this example, the stylesheet
comp.st.css from the previous example is imported into this stylesheet.
custom-selector alias conflicts with a local CSS class name, the exposed
pseudo-element targets the
The following examples demonstrate how to effectively use custom selectors in Stylable.
Some components might contain nested instances of themselves because they're a container or a "recursive" component. For example, a tree component might render itself.
If the component exposes any
pseudo-elements, it is a good practice to define them as
custom selectors with child selectors to avoid affecting the inner parts of internal instances.
The following example shows how a tree component exposes an icon.
Here you can use the icon
custom selector from the outside just like you would use any other
When you want to make internal parts of your component API more accessible, you can describe
For example, you can expose a
navigationBtn that enables you to style an internal gallery component's
You may have a component with several basic CSS classes and with corresponding
pseudo-elements. You could expose a combination
For example, a
navBtn matches any
btn CSS class nested in a
nav CSS class.
You could also use custom selectors to gather a collection of selectors into a single selector. For example, you may want to access media that includes both images and videos.
Aliasing multiple selectors in a
custom selector may generate lots of CSS that could affect performance.
For example, when you import the
Comp stylesheet (the selector described in the previous example) into another stylesheet, in the output the selector is split for each override.