README
Stacking Context Sass Module
The Stacking Context module manages z-indexes across a website or webapp so that the stacking order is unambiguous and easy to understand at a glance.
Most apps don't need z-index values greater than 10, so if your app has values like 999
or 10000
, then this module can probably help.
Table of Contents
- Stacking Context Sass Module
- API
- Examples
- Example 1: Using the default stacking context globally
- Example 2: Using a non-default stacking context globally
- Example 3: Using a specific stacking context list
- Example 4: Updating the default
$direction
- Example 5: Using a non-default
$direction
- Example 6: Using the
stacking-context
mixin to create scoped stacking contexts - Example 7: Using
selector.parse
to access another stacking context created by thestacking-context
mixin
API
stacking-context($indexes...)
Mixin A mixin to create a new stacking context. When used without parameters the mixin is equivalent to isolation: isolate
.
$indexes
Parameter A list of indexes to assign to $stacking-contexts
. The key will be the current selector (&
). selector.parse
can be used to recreate the key if necessary.
z($index, $context, $direction)
Function Meta | Details |
---|---|
returns | number or null |
A function to look up the numeric value from the named $index
in the specified $context
.
$index
Parameter Meta | Details |
---|---|
type | any map key |
The named index to look up in the specified stacking context.
$context
Parameter Meta | Details |
---|---|
default | default |
type | any map key or list |
The key of the stacking context to use from the module's configured $stacking-contexts
, or a list to use as the stacking context.
$direction
Parameter Meta | Details |
---|---|
default | $direction from the module configuration. |
type | ascending or descending |
The direction items are stacked in the specified stacking context.
See $direction
in module configuration for details.
Module Configuration
The Stacking Context module exposes the following variables for configuration.
$direction
Meta | Details |
---|---|
default | ascending |
type | ascending or descending |
The default direction items are stacked in the module.
When ascending
is specified, items earlier in the list will be covered by items later in the list. I.E. for (a, b, c)
: a
is covered by b
which is covered by c
.
When descending
is specified, items earlier in the list will cover items later in the list. I.E. for (a, b, c)
: a
covers b
which covers c
.
$stacking-contexts
Meta | Details |
---|---|
default | empty map |
type | map with keys of any type and values of lists |
The default stacking contexts to use globally. Any keys may be used. default
is used as the default $context
in the z
function.
Examples
Example 1: Using the default stacking context globally
@use 'path/to/stacking-context' as sc with (
// Stacking contexts can be globally configured for the module
$stacking-contexts: (
default: (
nav,
header,
modal
)
)
);
nav {
// The default stacking context is used if no value for `$context` is specified
z-index: sc.z(nav); // 1
}
header {
// By default items farther down the list have a higher z-index
z-index: sc.z(header); // 2
}
.modal {
z-index: sc.z(modal); // 3
}
Example 2: Using a non-default stacking context globally
@use 'path/to/stacking-context' as sc with (
$stacking-contexts: (
default: (
nav,
header,
modal,
),
modal: (
body,
footer,
header,
)
)
);
header {
// reads the `header` index from the `default` context
z-index: sc.z(header); // 2
}
.modal {
// @include stacking-context is the same as `isolation: isolate` when no
// parameters are provided.
isolation: isolate;
// reads the `modal` index from the `default` context
z-index: sc.z(modal); // 3
&__header {
// reads the `header` index from the `modal` context
z-index: sc.z(header, modal); // 3
}
&__body {
z-index: sc.z(body, modal); // 1
}
&__footer {
z-index: sc.z(footer, modal); // 2
}
}
Example 3: Using a specific stacking context list
@use 'path/to/stacking-context' as sc;
$indexes: (popup, menu, modal);
.popup {
z-index: sc.z(popup, $indexes); // 1
}
.menu {
z-index: sc.z(menu, $indexes); // 2
}
.modal {
z-index: sc.z(modal, $indexes); // 3
}
$direction
Example 4: Updating the default @use 'path/to/stacking-context' as sc with (
$direction: descending,
$stacking-contexts: (
default: (
modal,
header,
nav
)
)
);
nav {
// when `$direction: descending` is specified, items at the top of the list
// stack on top of items at the bottom of the list
z-index: sc.z(nav); // 1
}
header {
z-index: sc.z(header); // 2
}
.modal {
z-index: sc.z(modal); // 3
}
$direction
Example 5: Using a non-default @use 'path/to/stacking-context' as sc with (
$stacking-contexts: (
default: (
modal,
header,
nav
)
)
);
nav {
z-index: z(nav, $direction: descending); // 1
}
header {
z-index: z(header, $direction: descending); // 2;
}
.modal {
z-index: z(modal, $direction: descending); // 3;
}
stacking-context
mixin to create scoped stacking contexts
Example 6: Using the @use 'path/to/stacking-context' as sc;
.button-group {
// keep track of the current selector context
$ctx: &;
@include sc.stacking-context(default, focused); // isolation: isolate;
--border: 0.25em;
border: var(--border) solid transparent;
display: inline-flex;
flex-direction: row;
button {
appearance: none;
background-color: transparent;
border: var(--border) solid #888;
margin: calc(var(--border) * -1);
padding: 0.25em 0.5em;
// use the parent selector context to look up the default z-index
z-index: sc.z(default, $ctx); // 1
&:not(:first-child) {
margin-left: 0;
}
&:hover,
&:focus {
background-color: rgba(0, 0, 0, 0.2);
border-color: #000;
outline: 1px solid transparent;
// use the parent selector context to look up the focused z-index
// this allows the current button to show on top of its neighbors in
// the button group
z-index: sc.z(focused, $ctx); // 2
}
}
}
selector.parse
to access another stacking context created by the stacking-context
mixin
Example 7: Using @use 'path/to/stacking-context' as sc;
@use 'sass:selector';
.modal {
@include sc.stacking-context(body, footer, header); // isolation: isolate;
}
.modal-header {
z-index: sc.z(header, selector.parse(".modal")); // 3
}
.modal-body {
z-index: sc.z(body, selector.parse(".modal")); // 1
}
.modal-footer {
z-index: sc.z(footer, selector.parse(".modal")); // 2
}