@slithy/layers

@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

Reactive hook for reading the global layer stack store. Call with a selector to get reactive updates whenever the layer stack changes.

import { useLayerStackStore } from '@slithy/layers'

// Selector form — re-renders only when the selected value changes
const activeLayerId = useLayerStackStore(state => state.activeLayerId)

// Full store object — returns current state
const { activeLayerId, layers } = useLayerStackStore(state => state)

For imperative access (outside React components or in effects):

// Read current state
const { activeLayerId, layers } = useLayerStackStore.getState()

// Subscribe to changes
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({
  App: 0,
  Overlay: 5,
  Toast: 10,
})

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

LayerStackPriority

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

const LayerStackPriority = createLayerPriorities({
  App: 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>
)