react-cmp-selector

A powerful and extensible utility for selecting and manipulating React components based on attributes. Ideal for dynamic layouts, slotted rendering, and component injection patterns.

Table of Contents

• react-cmp-selector
  • Table of Contents
  • Installation
  • Motivation
  • Table of Proposals
  • Usage
    • 1. Basic Slot Matching
    • 2. Matching Multiple Components
    • 3. Combining Event Handlers
    • 4. Declarative API with <Slot>
    • 5. Fallback Slot Content
    • 6. Slot Markers
    • 7. Slot Validation
  • Use Cases
  • API Reference
    • getCmpByAttr<P>()
    • ComponentFinderProps
    • Slot
    • SlotUtils
  • Caveats
  • License

Installation

npm install react-cmp-selector

or using yarn:

yarn add react-cmp-selector

Motivation

React does not support named slots or dynamic selection of children out of the box. This utility solves that by providing:

• A hook to search through children by attribute
• A component-based API (<Slot>) for declarative slot usage
• Tools to inject props, merge handlers, and validate layout contracts

Table of Proposals

| Feature | Prop / Option | Type | Description | | ----------------------------- | -------------------------- | --------------------------------- | ------------------------------------------------------------- | | Attribute Matching | attribute | string | Attribute name to search for (default: 'data-slot') | | Value Matching | value / name | string | The value to match against the selected attribute | | Prop Merging | props | Partial<P> | Injected props to merge into the matched component(s) | | Function Merging Strategy | functionPropMerge | 'combine' \| 'override' | Defines how function props like onClick should be merged | | Debug Mode | debug | boolean | Enables logging of matching and merging behavior | | Match All | findAll | boolean | If true, returns all matching components instead of the first | | Hook Interface | getCmpByAttr() | — | Programmatic interface to extract and modify children | | Declarative API | <Slot> | — | React component alternative to the hook | | Slot Markers | SlotUtils.createMarker() | — | Creates a named slot wrapper component | | Slot Validation | SlotUtils.validate() | — | Dev-only validation for required slot presence | | Fallback Rendering | fallback | ReactNode | Rendered if no matching slot is found | | onFound Callback | onFound | (element: ReactElement) => void | Runs when a match is found (e.g. for side effects) |

Usage

1. Basic Slot Matching

Children

export function ChildComponents() {
  return (
    <>
      <div data-slot="header">Header</div>
      <div data-slot="body">Body</div>
      <div data-slot="footer">Footer</div>
    </>
  );
}

Parent

const header = getCmpByAttr({
  children: <ChildComponents />,
  value: "header",
  props: { className: "highlighted" },
});

Output

<div data-slot="header" class="highlighted">Header</div>

How It Works

• getCmpByAttr() searches children for data-slot="header".
• The match is cloned with the className prop added.

2. Matching Multiple Components

Children

function Buttons() {
  return (
    <>
      <button data-role="action-button">Save</button>
      <button data-role="action-button">Cancel</button>
    </>
  );
}

Parent

const buttons = getCmpByAttr({
  children: <Buttons />,
  attribute: "data-role",
  value: "action-button",
  findAll: true,
  props: { "data-tracked": true },
});

Output

<button data-role="action-button" data-tracked="true">Save</button>
<button data-role="action-button" data-tracked="true">Cancel</button>

3. Combining Event Handlers

Children

function CTA() {
  return (
    <button data-slot="cta" onClick={() => console.log("child")}>
      Click Me
    </button>
  );
}

Parent

const cta = getCmpByAttr({
  children: <CTA />,
  value: "cta",
  props: {
    onClick: () => console.log("parent"),
  },
  functionPropMerge: "combine",
});

Behavior

Console logs:

child
parent

4. Declarative API with <Slot>

export function Layout({ children }: { children: React.ReactNode }) {
  return (
    <div>
      <Slot name="header">{children}</Slot>
      <main>
        <Slot name="content">{children}</Slot>
      </main>
    </div>
  );
}

function PageContent() {
  return (
    <>
      <div data-slot="header">Welcome</div>
      <div data-slot="content">Hello, world!</div>
    </>
  );
}

<Layout>
  <PageContent />
</Layout>;

Output

<div>
  <div data-slot="header">Welcome</div>
  <main>
    <div data-slot="content">Hello, world!</div>
  </main>
</div>

5. Fallback Slot Content

<Slot name="hero" fallback={<div>Default Hero</div>}>
  {children}
</Slot>

If no data-slot="hero" is found, it renders:

<div>Default Hero</div>

6. Slot Markers

Marker Declaration

const HeroSlot = SlotUtils.createMarker("hero");

function Page() {
  return (
    <HeroSlot>
      <div className="hero-banner">Custom Hero</div>
    </HeroSlot>
  );
}

Parent

<Slot name="hero" fallback={<div>Default Hero</div>}>
  <Page />
</Slot>

7. Slot Validation

SlotUtils.validate(children, ["header", "footer"]);

• Dev-only.
• Warns if data-slot="header" or footer is missing in children.

Use Cases

• Composable Layouts: Dynamically slot content into shared layouts.
• Design Systems: Enable flexible API layers with predictable slot names.
• Multi-brand / White-label UIs: Inject branding-specific content without hardcoding.
• Next.js Layouts: Use context + slots to bridge app/layout.tsx and pages.
• Dynamic Prop Injection: Apply analytics, A/B testing, or class injection to specific slots.

API Reference

getCmpByAttr<P>()

function getCmpByAttr<P>(
  options: ComponentFinderProps<P>
): ReactNode | ReactNode[] | null;

ComponentFinderProps

interface ComponentFinderProps<P = unknown> {
  children: ReactNode;
  attribute?: string;
  value?: string;
  props?: Partial<P>;
  debug?: boolean;
  findAll?: boolean;
  onFound?: (component: ReactElement) => void;
  functionPropMerge?: "combine" | "override";
}

Slot

<Slot
  name="footer"
  props={{ className: "sticky" }}
  fallback={<DefaultFooter />}
>
  {children}
</Slot>

SlotUtils

SlotUtils.createMarker(name: string, attribute?: string): Component
SlotUtils.validate(children: ReactNode, requiredSlots: string[], attribute?: string): void

Caveats

• Next.js layouts require a shared context if crossing page boundaries.
• getCmpByAttr only works on elements rendered within the same render cycle.
• This is not a DOM query tool – it’s entirely based on React element trees.

License

MIT License