@zzzzbov/stacking-context

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
    • Mixin stacking-context($indexes...)
      • Parameter $indexes
    • Function z($index, $context, $direction)
      • Parameter $index
      • Parameter $context
      • Parameter $direction
    • Module Configuration
      • $direction
      • $stacking-contexts
  • 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 the stacking-context mixin

API

Mixin stacking-context($indexes...)

A mixin to create a new stacking context. When used without parameters the mixin is equivalent to isolation: isolate.

Parameter $indexes

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.

Function z($index, $context, $direction)

Meta	Details
returns	number or null

A function to look up the numeric value from the named $index in the specified $context.

Parameter $index

Meta	Details
type	any map key

The named index to look up in the specified stacking context.

Parameter $context

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.

Parameter $direction

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
}

Example 4: Updating the default $direction

@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
}

Example 5: Using a non-default $direction

@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;
}

Example 6: Using the stacking-context mixin to create scoped stacking contexts

@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
    }
  }
}

Example 7: Using selector.parse to access another stacking context created by the stacking-context mixin

@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
}