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.

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