React-compound-composer NPM

Description

This library aims to make it easier to develop and maintain Compound Components by encapsulating context creation and compound composition logic under two core helpers.

Check those amazing posts to learn more about Compound Components:

Examples/Demo

Stackblitz Collection

Simple Counter Example: An almost in-line example of a Counter with its own state. Here just for a very quick proof-of-concept.
A Better Structured Example: An example of an Accordion compound
Nested Compounds Example: An example of nested compound
Flattened Root Example: An example of how you can flatten Root components

How to Use?

1. Create your Context

Start off by creating your context. This context will be available via a hook on all the sub-components. A good way to keep a dispatch-editable state across the components.

import { contextBuilder } from "react-compound-composer";

const {
  Consumer: CounterConsumer, // Consumer is also returned, just for convenience
  Provider: CounterProvider,
  useContext: useCounterContext,
} = contextBuilder(() => {
  const [count, setCount] = useState(0);

  return {
    count,
    increase: (count: number) => setCount((c) => c + count),
    decrease: (count: number) => setCount((c) => c - count),
  };
});

2. Create your Root & Sub Components

Create a few components to be composed under the compound.

import React from "react";

const CounterRoot = (props: React.PropsWithChildren) => {
  return (
    <div
      style={{
        display: "flex",
        flexDirection: "column",
        gap: 10,
        alignItems: "center",
      }}
    >
      {props.children}
    </div>
  );
};

import React from "react";

const CounterCount = () => {
  const ctx = useCounterContext();
  return <span>{ctx.count}</span>;
};

import React from "react";

const CounterIncrease = () => {
  const ctx = useCounterContext();
  return <button onClick={() => ctx.increase(1)}>Increase</button>;
};

import React from "react";

const CounterDecrease = () => {
  const ctx = useCounterContext();
  return <button onClick={() => ctx.decrease(1)}>Decrease</button>;
};

3. Compose your Compound with them!

Finally compose your Compound with the components you've created.

import { compoundBuilder } from "react-compound-composer";

export const Counter = compoundBuilder({
  name: "Counter",
  provider: CounterProvider,
  components: {
    Root: CounterRoot,
    Count: CounterCount,
    Increase: CounterIncrease,
    Decrease: CounterDecrease,
  },
});

4. Enjoy your Compound!

Use your compound as desired.

export default function App() {
  return (
    <main>
      <Counter.Root>
        <Counter.Increase />
        <Counter.Count />
        <Counter.Decrease />
      </Counter.Root>
    </main>
  );
}

How to Flatten `Root` Components?

If you prefer using the root components without actually using their Root properties, you can set the flattenRoot option to true. Like so:

import { compoundBuilder } from "react-compound-composer";

export const Counter = compoundBuilder({
  name: "Counter",
  provider: CounterProvider,
  flattenRoot: true,
  components: {
    Root: CounterRoot,
    Count: CounterCount,
    Increase: CounterIncrease,
    Decrease: CounterDecrease,
  },
});

and use the Compound like so:

export default function App() {
  return (
    <main>
      <Counter>
        <Counter.Increase />
        <Counter.Count />
        <Counter.Decrease />
      </Counter>
    </main>
  );
}

License

For any part of this work for which the license is applicable, this work is licensed under the Attribution-ShareAlike 4.0 International license. (See LICENSE).