Customize Components
Learn how to customize the style of all components using Sass variables

Components Structure

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:

  • folder acme-dashboard
    • folder library
      • folder extend
        • folder components
          • description _card.scss
          • description _badge.scss
          • description _select2.scss
          • description _uppy.scss
          • description +36 more files
      • folder components
        • folder card
          • description _defaults.scss
        • folder badge
          • description _defaults.scss
        • folder select2
          • description _defaults.scss
        • folder uppy
          • description _defaults.scss
        • folder +43 more

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.

Customizing a Component

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.

Accessing theme colors

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)
);

The highlighted 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 primary-500.

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 light-cerulean.

PRO TIP you can use all of these modules within your custom .scss files at @assets/style/main.scss, which enables you to access all theming config options to further extend Nile Dashboard the right way.

Next Up

Learn how to customize bootstrap by adding unique utility classes or changing the default breakpoints
Learn how to optimize and prepare your final package for production and reach great levels of optimization using frontal.js features

{title}