Customizing
You can customize Shoelace without editing core files or using a preprocessor. To add customizations, simply override one or more of the variables found in the :root
block of shoelace.css
.
For example, you can customize the default text color, background color, and the primary color by adding this to your stylesheet:
:root {
--body-color: white;
--body-bg-color: black;
--state-primary: #09d;
}
You don’t need to include all of the variables. You only need to override the ones you actually want to customize.
Additional variables can be found in the :root
block of each component’s stylesheet. For example, to customize alerts, refer to the top of alerts.css
for a list of variables.
Using Variables
You can use any of Shoelace’s variables in your own stylesheet. This makes it easy to reuse values without hardcoding them. It also provides a foundation for extending Shoelace with your own custom components.
.your-selector {
color: var(--state-danger);
}
If you’re not familiar with CSS variables, this article will bring you up to speed. There’s also an interactive demo if you want to experiment.
Creating Custom Components
You can create custom components to extend Shoelace’s functionality. Here are some best practices to keep things consistent and easy for others to understand.
Familiarize yourself with Shoelace’s naming conventions. A custom accordion component, for example, would have a class name such as accordion
, modifier classes such as accordion-open
, and variable names that look like --accordion-bg-color
. Try to follow similar patterns as much as possible.
Define new variables when it makes sense to. Take a look at how existing components are defined. Many use core variables instead of hardcoded properties as default values. This makes it easy for users to customize things quickly, but still provides enough flexibility to style individual components.
Semantic markup is strongly encouraged. Custom components should use the most appropriate elements and the minimal amount of markup required.
Keep everything together. Each component should be in its own folder along with its stylesheets, scripts, and documentation. Components can use core variables, but they shouldn’t depend on other components’ styles or scripts to work. This makes it easier to add or remove components from your app without worrying about dependencies.