React Slot Engine

A lightweight, highly type-safe React utility that brings Vue-style declarative and scoped slots to React components.

Designed specifically for building robust UI ecosystems, this engine allows you to author highly flexible, compound components without the boilerplate of traditional prop-drilling or complex React context setups.

Features

• 🎯 Vue-Style Declarative Slots: Define named slots directly within your component's children.
• 🛡️ First-Class TypeScript Support: Deeply integrated generics ensure strict type safety for slot names and scoped data payloads.
• 🔄 Scoped Slots: Pass internal state or data from the parent component back down to the specific slot content.
• 💉 Attribute Injection: Seamlessly merge React props and className strings directly into slotted elements.
• 🎛️ Programmatic API: Access a convenient $slots proxy for imperative slot rendering.
• 🪂 Fallback Content: Easily define default UI if a consumer omits a specific slot.

Installation

(Assuming you publish this to npm/yarn/pnpm)

npm install @sse-ui/slot

Basic Usage

First, initialize the engine with a type map defining your available slots.

// card-engine.tsx
import { createSlotEngine } from "@sse-ui/slot";

// Define the exact slots your component will accept
type CardSlots = {
  header: undefined;
  footer: undefined;
};

// Create and export the Slot component and the hook
export const { Slot, useSlots } = createSlotEngine<CardSlots>();

Next, use the useSlots hook inside your wrapper component to place the rendered slots.

// Card.tsx
import React from "react";
import { Slot, useSlots } from "./card-engine";

export function Card({ children }: { children: React.ReactNode }) {
  const { renderSlot, defaultSlot } = useSlots(children);

  return (
    <div className="border rounded-lg shadow-sm">
      {/* Render named slots */}
      <header className="p-4 border-b">
        {renderSlot("header", { fallback: <h2>Default Title</h2> })}
      </header>

      {/* Render any children not wrapped in a <Slot> */}
      <main className="p-4">{defaultSlot}</main>

      <footer className="p-4 border-t bg-gray-50">
        {renderSlot("footer")}
      </footer>
    </div>
  );
}

Card.Slot = Slot;

Finally, consumers can use your component intuitively:

// App.tsx
import { Card } from "./Card";

function App() {
  return (
    <Card>
      <Card.Slot name="header">
        <h1 className="text-xl font-bold">Custom Header</h1>
      </Card.Slot>

      <p>This paragraph automatically goes into the default slot.</p>

      <Card.Slot name="footer">
        <button>Confirm</button>
      </Card.Slot>
    </Card>
  );
}

Advanced Features

Scoped Slots (Data Passing)

You can pass internal component data back to the slot consumer, allowing them to render UI based on the parent's state.

// Define the data type in your Slot Map
type ListSlots = {
  item: { index: number; active: boolean };
};

const { Slot, useSlots } = createSlotEngine<ListSlots>();

// Inside your component:
renderSlot("item", { data: { index: 0, active: true } });

// Usage by consumer:
<Slot name="item">
  {({ index, active }) => (
    <li className={active ? "font-bold" : ""}>Item #{index}</li>
  )}
</Slot>;

Vue-Style Attribute Injection

Sometimes the parent component needs to enforce certain classes or HTML attributes on a slot, regardless of what the user passes in. The injectProps option smartly merges properties and concatenates className strings.

// Inside your component:
renderSlot("trigger", {
  injectProps: {
    className: "base-trigger-class",
    "aria-expanded": isOpen,
  },
});

// Usage by consumer:
<Slot name="trigger">
  <button className="user-custom-class">Open Menu</button>
</Slot>;

// Output HTML:
// <button class="base-trigger-class user-custom-class" aria-expanded="true">Open Menu</button>

Programmatic API ($slots)

If you prefer a more programmatic approach to checking or rendering slots, the engine exposes a $slots Proxy.

const { $slots, hasSlot } = useSlots(children);

// Check if a slot exists
if (hasSlot("header")) {
  console.log("Header slot provided!");
}

// Execute the proxy to render
return (
  <div>
    {$slots.header?.({ someData: 123 })}
    {$slots.default?.()}
  </div>
);

API Reference

createSlotEngine<SlotMap, DynamicData>()

Initializes the engine.

• SlotMap: A TypeScript interface mapping slot names to their respective scoped data types.
• Returns: An object containing the <Slot> component and the useSlots hook.

<Slot name="..." />

The declarative wrapper for slot content.

• name: The strict-typed identifier for the slot.
• children: Can be standard React nodes or a function (data) => ReactNode if consuming scoped data.

useSlots(children)

The hook used inside your parent component to process children.

• renderSlot(name, options?): Renders a specific slot. Options include fallback, data (for scoped slots), and injectProps.
• defaultSlot: An array of all children not wrapped in a <Slot>.
• hasSlot(name): Returns a boolean indicating if the consumer provided the named slot.
• $slots: A proxy object for programmatic slot rendering ($slots.slotName(data)).

*** Tip for Library Authors: Because the engine relies heavily on generic inference, ensure your build step correctly preserves TypeScript declarations so consumers of your UI ecosystem retain full autocomplete capabilities.