@slithy/layers

Layer and z-index management for React UIs. Tracks a stack of mounted layers and determines which is "active" (highest priority). Useful for managing focus, keyboard interactions, and visual stacking of overlaid components like modals and drawers.

Installation

npm install @slithy/layers

Peer dependencies: react@^17 || ^18 || ^19

LayerProvider

Wraps a component to register it in the global layer stack. On mount, the layer is added to the stack; on unmount, it is removed.

import { LayerProvider, LayerStackPriority } from '@slithy/layers'

<LayerProvider id="my-modal" zIndex={LayerStackPriority.Modal}>
  <MyModal />
</LayerProvider>

Props:

| Prop | Type | Default | Description | |---|---|---|---| | id | string | auto-generated | Unique identifier for this layer | | zIndex | number | 0 | Priority in the stack — higher wins | | isActive | boolean | true | If false, layer is not registered in the stack | | children | ReactNode | — | |

useLayerState

Hook to read state from the nearest LayerProvider. Must be called within a LayerProvider.

// Selector form — returns selected value, re-renders only on change
const layerIsActive = useLayerState(s => s.layerIsActive)

// No-arg form — returns full store object
const { getState, setState } = useLayerState()

Store shape (LayerStore):

type LayerStore = {
  layerID: string
  layerIsActive: boolean  // true when this layer has the highest priority
  zIndex: number
}

useLayerStackStore

Direct access to the global layer stack store. Useful for reading or subscribing to stack-wide state outside of a LayerProvider.

import { useLayerStackStore } from '@slithy/layers'

const { activeLayerId, layers } = useLayerStackStore.getState()

const unsubscribe = useLayerStackStore.subscribe(() => {
  const { activeLayerId } = useLayerStackStore.getState()
})

createLayerPriorities

Factory for defining a custom set of layer priorities. Returns a frozen readonly object.

import { createLayerPriorities } from '@slithy/layers'

const MyPriorities = createLayerPriorities({
  Base: 0,
  Overlay: 5,
  Toast: 10,
})

<LayerProvider zIndex={MyPriorities.Toast}>
  <ToastStack />
</LayerProvider>

LayerStackPriority

The built-in default priority set, defined with createLayerPriorities:

const LayerStackPriority = createLayerPriorities({
  Base: 0,
  Modal: 1,
  Toasts: 2,
})

MockLayerProvider

A test utility that provides a mock layer context with hardcoded values. Use this to render components that depend on LayerProvider without needing a real stack.

import { MockLayerProvider } from '@slithy/layers'

render(
  <MockLayerProvider>
    <ComponentUnderTest />
  </MockLayerProvider>
)