Elevations

    Elevations are used to establish and maintain functional boundaries between Document Object Model trees to enable better functional encapsulation. You can create sets of elevations using our Sass theming library.

    Overview

    Elevations in Ignite UI for Angular are declared as a map of 25 elements. Each element is a key-value pair where the key is the elevation level name (0..24) and the value is a list of 3 box-shadow declarations. We allow you to generate new sets of elevations where you can define the color for the shadows. Additionally, we expose functions for retrieving a specific elevation level from the elevations map. We expose a global variable $elevations that is used across components by default. If you've not read the CSS variables documentation related to Elevations, we suggest you do that first before reading on.

    Usage

    The following section demonstrates how to create and retrieve custom elevations.

    Configuring Elevations

    To change the colors used by the default elevation presets, you need to configure the elevations preset module.

    // Define the 3 elevation colors
@use 'igniteui-theming/sass/elevations/presets' as * with(
    $color-1: rgb(153, 191, 170), // Umbra
    $color-2: rgb(92, 134, 141), // Penumbra
    $color-3: rgb(92, 61, 70) // Ambient
);

@include elevations($material-elevations);

    Retrieving Elevations

    To retrieve a set of box-shadows from the elevations map you can pass up to two arguments to the elevation function - an elevation map and the wanted elevation level. It returns a list of 3 box shadows for the given level.

    If you want to retrieve the elevation from the default $elevations map, you can omit the first argument.

    // Returns elevation 1 shadows
$elevation-1: elevation(1);

// Returns elevation 1 shadows
$my-elevation-1: elevation($name: 1);

    Passing Elevations to Themes

    Several theme mixins allow you to pass an elevations map. Most notably, the theme has a parameter named $elevations which allows you to update the elevations for all component themes.

    Force all component themes to use your custom elevations:

    @include theme(
    //...
    $elevations: $my-elevations
);

    In addition to this, you can tell the theme to ignore/not use elevations completely:

    @include theme(
    //...
    $elevations: $my-elevations,
    $elevation: false // disables all elevations
);

    Some component themes also accept the $elevations parameter to allow you to pass custom elevation for their instances only.

    For instance, the card component does support passing custom elevations. To find out which components accept a custom elevations map, take a look at their Sass documentation. Each component uses only specific levels from the elevations map, those too are listed in the component's Sass docs.

    @include card(card-theme(
    //...
    $elevations: $my-elevations,
));

    Since the elevation function returns a list of box shadows, you can use the return value of that function to modify only certain elevations in your component themes.

    $card-theme: card-theme(
    $resting-shadow: elevation(10)
);

@include card($card-theme);

    This compiles to:

    .igx-card {
  box-shadow: 
    0 6px 6px -3px rgba(0, 0, 0, 0.26),
    0 10px 14px 1px rgba(0, 0, 0, 0.12),
    0 4px 18px 3px rgba(0, 0, 0, 0.08);
}

    You can also pass simple box shadows without taking advantage of the elevation function:

    $card-theme: card-theme(
    $resting-shadow: 0 10px 10px 10px #666
);

.my-card {
  @include card($card-theme);
}

    Here is the result from the above snippet:

    .my-card .igx-card {
  /* ... */
  box-shadow: 0 10px 10px 10px #666;
}

    Custom Elevations

    It is possible to create an elevations map that doesn't adhere to the Material Design Guidelines as generated by the elevations function. Make sure your custom elevation maps contain at least 25 elevation levels. Here's the elevations map signature our themes expect to build correctly:

    // Omitted levels 2 through 23 for brevity
$elevations: (
    0: box-shadow(...),
    1: box-shadow(...),
    ...
    24: box-shadow(...)
);

    Elevation Schema Declarations

    The elevation levels are also used in theme schema declarations. More on that in the Schema section of the documentation.

    API References

    Additional Resources

    Our community is active and always welcoming to new ideas.