The concept used within Nile Dashboard for customizing components is the same as customizing the theme itself, all customizations reside within the
extend directory, lets take a look for the directories of interest we should look at when customizing components:
In the previous structure, the directory colored green
extend is the only valid place to add customizations to components, whereas the directory colored red
components, is the where to find the default values and reference to follow when customizing.
Components in this documentation also provide a tab called
Sass Variables which can be used as a reference for the available options to use for customizing certain components.
In this section, we will take the
card component as an example, the location we should use to add our customization to the card component will be
@library/extend/components/_card.scss, by default, that file looks as follows:
// @library/extend/components/_card.scss @forward "@library/components/card/defaults";
Looking at the forwarded file, we can see the name of the available variables we are allowed to extend and customize, for this tutorial we just want to increase the border radius and border width, so we can do the following:
// @library/extend/components/_card.scss @forward "@library/components/card/defaults" with ( $card-border-width: 2px, $card-border-radius: 12px );
Saving the previous file will now update the card look all over the dashboard.
As explained in the Design System guide, each theme has a configuration map, within each config map there are several property keys that you would want to access, for example, primary and variant colors, or tunings of each of these colors and lastly the properties map.
In this section we will give an example for each option type and how to access them, the commonly used sass module for this is
@library/sass/modules/property, lets look at an example of using that module:
// @library/extend/components/_card.scss @use "@library/sass/modules/property"; @forward "@library/components/card/defaults" with ( $card-border-color: property.get(primary-500) );
property.get method takes a parameter, that parameter is the name of the CSS property you want to access, for that example, we are changing the card border color to be
The same can be done for other variants, lets look at a few examples
// @library/extend/components/_card.scss @use "@library/sass/modules/property"; // Access a variant color $example1: property.get(success); // Access a certain tint of a variant color $example2: property.get(success-t-08) // Or the contrast (text) color of a certain variant $example3: property.get(success-t-08-contrast) // Access a color from the color palette $example4: property.get(red-500); // Access theme properties $example5: property.get(text-surface-medium);
Note that some components' configuration requires that just the name of the theme property to be provided and not the actual value of it, for example, the
select2 component, defines the following config variable as follows:
// @library/components/select2/_defaults.scss // ... $dx-select2-input-color: form-input-text-color !default; // ...
Note how the property
form-input-text-color is provided without the use of the
property.get function, that indicates, that the implementation of the
select2 component is using the
property module on its own.
With that said, the primary reason behind the use of the
property module, is that it returns a CSS property instead of the actual raw value, which in turn enables switching between light and dark modes easily, lets look at an example of how the
property.get returns values:
// @library/extend/components/_card.scss @use "@library/sass/modules/property"; // Access a variant color $example1: property.get(success); // $example1 = var(--success);
Simple right? Now, what if we want to access the raw value for a certain theme config property, we would then use another module named
theme, that module requires that you pass which theme to return the value of, below is an example of how the
theme module is used from the
select2 component as well:
// @library/components/select2/_defaults.scss @use "@library/sass/modules/theme"; // ... $dx-select2-input-arrow-color: theme.get(default, true, form-input-select-indicator-color) !default; // ...
As seen in the previous example, the use of the
theme.get function returns the actual raw value of the property
form-input-select-indicator-color from the
default theme, which is the default case is
@assets/style/main.scss, which enables you to access all theming config options to further extend Nile Dashboard the right way.