react-layered

Welcome to react-layered! If you've ever found yourself lost in the jungle of z-index layers, fighting the chaos of overlapping UI elements, then buckle up! This tiny, mighty package is your guide to taming that wild z-index safari in your React projects. 🌿👓

Features

• 🔒 Type Safe: Built with TypeScript, offering that snug, error-proof comfort.
• 🪶 Super Lightweight: Less than 2KB. Using zero dependencies. It's almost like it's not even there!
• 🧘 Easy Configuration: Set up your layers once, use them with zen-like calm.

Setup

Installation

First, install the package using your favourite package manager:

npm install react-layered
yarn add react-layered
pnpm add react-layered
bun add react-layered

Configuring Layers

Create a hook to configure your layers. This example sets up common UI layers like background, navigation, and modals:

// hooks/useLayer.ts
import { useLayerConfig } from "react-layered";

// Initialize the layer configuration with an array of layer descriptors.
// Lower layers in the list have a higher z-index by default.
export default useLayerConfig([
  // Define simple layers using strings.
  "navigation",
  "footer",
  "dropdown",

  // Define a layer with additional properties using an object.
  { key: "tooltip" },

  // Allocate a range of zIndex values for a layer by defining 'slots'.
  // For example, allocate 100 zIndex slots for the "toast" layer.
  // You can find an example how to use the slots below.
  { key: "toast", slots: 100 },

  // Create composite layers with multiple sub-layers using the 'parts' property.
  // You can find an example how to access the parts below.
  { key: "modal", parts: ["backdrop", "content"] },
]);

Usage

Using the style object

import useLayer from "../hooks/useLayer";

const MyNavigation = () => {
  const { style } = useLayer("navigation");
  return <div style={style}>This is a navigation!</div>;
};

Using only the zIndex

import useLayer from "../hooks/useLayer";

const MyTooltip = () => {
  const { zIndex } = useLayer("tooltip");
  return <div style={{ zIndex }}>This is a tooltip!</div>;
};

Using different parts of a layer

import useLayer from "../hooks/useLayer";

const MyModal = () => {
  const { style } = useLayer("modal");

  // Or like this:
  // const { style: backgroundStyle } = useLayer("modal.background");
  // const { style: contentStyle } = useLayer("modal.content");

  return (
    <div style={style.background}>
      <p style={style.content}>Hello, I'm on top!</p>
    </div>
  );
};

Using multiple slots of a layer

import useLayer from "../hooks/useLayer";

const MyToast = ({ index }: { index: number }) => {
  // Pass the index of the item as the second argument.
  // Make sure it starts counting from 0.
  const { zIndex } = useLayer("toast", index);
  return <div style={{ zIndex }}>This works with multiple toasts!</div>;
};

Using different stacking contexts

// hooks/useLayer.ts
import { useLayerConfig } from "react-layered";

export const useFixedLayer = useLayerConfig([
  "modal",
  "alert",
  "toast",
  "tooltip",
]);

export const useAbsoluteLayer = useLayerConfig([
  "navigation",
  "footer",
  "dropdown",
]);

API

useLayerConfig(layers, options)

Use this function to generate your own useLayer hook.

| Parameter | Required | Type | Description | | --------- | -------- | ----------------------------- | ---------------------------------------------------------------------- | | layers | ✅ | (string | LayerObject)[] | An array of LayerObjects or strings defining the layers in the system. | | config | ❌ | LayersConfig | An optional configuration object specifying additional settings. |

LayerObject

| Property | Required | Type | Default | Description | | -------- | -------- | ------ | ------- | ------------------------------------------------ | | key | ✅ | string | - | The key of the layer. | | slots | ❌ | number | 1 | Extend the layer across multiple z-index levels. |

LayersConfig

| Property | Required | Type | Default | Description | | --------- | -------- | ------- | ------- | ------------------------------------------- | | start | ❌ | number | 1 | The initial value to start the zIndex with. | | reverse | ❌ | boolean | false | Reverse the layer order. |

useLayer(key[, slot])

This function is a custom hook that you can create using useLayerConfig.

| Parameter | Required | Type | Description | | --------- | -------- | ------ | --------------------------------------------------------------------------------------------- | | key | ✅ | string | The key of the layer. | | slot | ❌ | number | The slot to be used, starting at 0. Applicable only when 'slots' is configured for the layer. |