react-slot-fill ·

Slot & Fill component for merging React subtrees together.

Check out the simple demo on glitch (view source)

Installation

npm install react-slot-fill --save

Check out the examples locally

git clone https://github.com/camwest/react-slot-fill
cd react-slot-fill
npm start

Usage

Note These examples use React Fiber Alpha

Toolbar.js

1import { Slot, Fill } from 'react-slot-fill';
2
3const Toolbar = (props) =>
4  <div>
5    <Slot name="Toolbar.Item" />
6  </div>
7
8export default Toolbar;
9
10Toolbar.Item = (props) =>
11  <Fill name="Toolbar.Item">
12    <button>{ props.label }</button>
13  </Fill>

Feature.js

1import Toolbar from './Toolbar';
2
3const Feature = () =>
4  [
5    <Toolbar.Item label="My Feature!" />
6  ];

App.js

1import Toolbar from './Toolbar';
2import Feature from './Feature';
3
4import { Provider } from 'react-slot-fill';
5
6const App = () =>
7  <Provider>
8    <Toolbar />
9    <Feature />
10  </Provider>
11
12ReactDOMFiber.render(
13  <App />,
14  document.getElementById('root')
15);

Components

Creates a Slot/Fill context. All Slot/Fill components must be descendants of Provider. You may only pass a single descendant to Provider.

1interface Provider {
2  /**
3   * Returns instances of Fill react components
4   */
5  getFillsByName(name: string): Fill[];
6  /**
7   * Return React elements that were inside Fills
8   */
9  getChildrenByName(name: string): React.ReactChild[];
10}

getFillsByName and getChildrenByName are really useful for testing Fill components. See src/lib/__tests/Provider.test.tsx for an example.

Expose a global extension point

1import { Slot } from 'react-slot-fill';

Props

1interface Props {
2  /**
3   * The name of the component. Use a symbol if you want to be 100% sue the Slot
4   * will only be filled by a component you create
5   */
6  name: string | Symbol;
7
8  /**
9   * Props to be applied to the child Element of every fill which has the same name.
10   *
11   *  If the value is a function, it must have the following signature:
12   *    (target: Fill, fills: Fill[]) => void;
13   *
14   *  This allows you to access props on the fill which invoked the function
15   *  by using target.props.something()
16   */
17  fillChildProps?: {[key: string]: any}
18
19  /**
20   * A an optional function which gets all of the current fills for this slot
21   * Allows sorting, or filtering before rendering. An example use-case could
22   * be to only show a limited amount of fills.
23   *
24   * By default Slot injects an unstyled `<div>` element. If you want greater
25   * control over presentation use this function.
26   *
27   * @example
28   * <Slot name="My.Slot">
29   * {(items) => <Component>{items}</Component>}
30   * </Slot>
31   */
32  children?: (fills) => JSX.Element
33}

Render children into a Slot

1import { Fill } from 'react-slot-fill';

Props

1interface Props {
2  /**
3   * The name of the slot that this fill should be related to.
4   */
5  name: string | Symbol
6
7  /**
8   * one or more JSX.Elements which will be rendered
9   */
10  children: JSX.Element | JSX.Element[]
11}

You can add additional props to the Fill which can be accessed in the parent node of the slot via fillChildProps.