react-nanny

Utils to manage your React Children; find and filter children by type or custom function, enforce child content, and more!

Hello friend. Have you ever had the need to:

• ...query a set of React Children by type or otherwise?
• ...reject and remove some of your children for whatever [judgement free] reason?
• ...ensure that your children return content at some level?

If you answered yes to any of those questions, then it sounds like your children could use a nanny to help bring order to the chaos...

Version: 2.15.0

Dependencies

react-nanny doesn't have any dependencies. However, it does have a peer dependency of "react": ">=16.0.0" which you most likely satisfy if you're the kind of person who's looking for utils for React children.

Example

This is simple example of how you can program defensively (your consumer can't just throw anything unexpected in children and have it render) and it shows how you can manipulate your children to place them anywhere in the rendered output.

Below, we have a ToDo list of Items. We first get all child Items—all other children will be ignored. We then find two lists of children that are completed and incomplete.

import React from 'react';
import { getChildrenByType, getChildren } from 'react-nanny';
import Item from './Item';

export const ToDoList ({ children }) => {
  // Get all children of type Item
  const items = getChildrenByType(children, [Item]);

  // Find all incomplete and complete Items
  const incomplete = getChildren(items, child => !child.props.completed);
  const completed = getChildren(items, child => child.props.completed);

  return (
    <>
      <div>
        <h3>To Do</h3>
        <ul>
          {incomplete}
        </ul>
      </div>
      <div>
        <h3>Completed</h3>
        <ul>
          {completed}
        </ul>
      </div>
    </>
  );
};

Summary of Utils

Click on each function name for details and examples

function	Description
getChild	Gets first child by specified predicate
getChildDeep	Gets first child by specified predicate (deep search)
getChildByType	Gets first child by specified type
getChildByTypeDeep	Gets first child by specified type (deep search)
getChildren	Gets all children by specified predicate
getChildrenDeep	Gets all children by specified predicate (deep search)
getChildrenByType	Gets all children by specified type
getChildrenByTypeDeep	Gets all children by specified type (deep search)
getChildrenWithDescendant	Gets all children by specified predicate or that have a descendant node in their lineage which matches the predicate
getChildrenWithDescendantByType	Gets all children by specified type or that have a descendant node in their lineage which match the specified type
getDescendantDepth	Gets the depth to the first descendant (or self) of each root child that match the specified predicate
getDescendantDepthByType	Gets the depth to the first descendant (or self) of each root child that match the specified types
noEmptyChildrenDeep	Ensure that there is some level of content and not just a bunch of empty divs, spans, etc (deep search)
overrideProps	Immutably override props of the children of the original component and (optionally) the original component
overridePropsDeep	Immutably override props of the children and all descendants (deep)
removeChildren	Removes all children by specified predicate
removeChildrenDeep	Removes all children by specified predicate (deep search)
removeChildrenByType	Removes all children by specified type
removeChildrenByTypeDeep	Removes all children by specified type (deep search)
typeOfComponent	Gets the string type of the component's {customTypeKey}, string type of the core html (JSX intrinsic) element, or the function type

---

What can I use to derive types for a comparison?

You can use an imported type, a React.ReactNode, value from typeOfComponent, a string type for an HTML (JSX Intrinsic) element, or a string representation of the type by using the customTypeKey feature.

Imported Type

import { getChildByType } from 'react-nanny';
import MyComponent from './MyComponent';

getChildByType(children, [MyComponent]);

React.ReactNode

import { getChildByType, removeChildrenByType } from 'react-nanny';
import MyComponent from './MyComponent';

const child = getChildByType(children, [MyComponent]);
...
removeChildrenByType(children, [child]);

typeOfComponent

import { getChildByType, removeChildrenByType, typeOfComponent } from 'react-nanny';
import MyComponent from './MyComponent';

const child = getChildByType(children, [MyComponent]);
...
removeChildrenByType(children, [typeOfComponent(child)]);

String type for HTML (JSX Intrinsic) Elements

import { getChildByType } from 'react-nanny';

getChildByType(children, ['div']);

customTypeKey

What the heck is a customTypeKey?

One simple way to be able to define and identify a type on a component and ensure that it is the same in development builds and production builds is to add a constant prop that contains the string type. Consider the following hypothetical component:

import React from 'react';

const Hello = ({ __TYPE }) => <div>Hello World!</div>;

Hello.defaultProps = {
  __TYPE: 'Hello',
};

The Hello has a prop __TYPE that has a value of 'Hello'. We can query against this value and know that it's reliable regardless of environment.

The customTypeKey in react-nanny defines what the name of this prop is. In our example, customTypeKey would be '__TYPE' to query using this technique

import { getChildByType } from 'react-nanny';

getChildByType(children, ['Hello']);

Let's say you don't like __TYPE and what to use your own value such as: CUSTOM. You can accomplish this by providing the name for the customTypeKey:

import { getChildByType } from 'react-nanny';

getChildByType(children, ['Hello'], { customTypeKey: 'CUSTOM' });

For more information on how to enforce the integrity of the customTypeKey, check out my Medium article: Find & Filter React Children By Type

forwardRef

Because React.forwardRef components are higher order components, determining their type becomes tricky. The only way to reliably determine their type is to use the customTypeKey method outlined above.

Package Contents

Within the module you'll find the following directories and files:

package.json
CHANGELOG.md -- history of changes to the module
README.md -- this file
/lib
  └───/es5
    └───/getChild
      └───index.d.ts - 1.23 KB
      └───index.js - 1.81 KB
    └───/getChildByType
      └───index.d.ts - 4.16 KB
      └───index.js - 6.08 KB
    └───/getChildren
      └───index.d.ts - 1.21 KB
      └───index.js - 2.07 KB
    └───/getChildrenByType
      └───index.d.ts - 3.86 KB
      └───index.js - 5.41 KB
    └───/getChildrenWithDescendant
      └───index.d.ts - 638 Bytes
      └───index.js - 1.31 KB
    └───/getChildrenWithDescendantByType
      └───index.d.ts - 2.26 KB
      └───index.js - 3.02 KB
    └───/getDescendantDepth
      └───index.d.ts - 1.14 KB
      └───index.js - 2.46 KB
    └───/getDescendantDepthByType
      └───index.d.ts - 2.39 KB
      └───index.js - 3.93 KB
      └───index.d.ts - 1.1 KB
      └───index.js - 4.23 KB
    └───/noEmptyChildren
      └───index.d.ts - 1.75 KB
      └───index.js - 3.43 KB
    └───/overrideProps
      └───index.d.ts - 2.72 KB
      └───index.js - 4.66 KB
    └───/removeChildren
      └───index.d.ts - 1.22 KB
      └───index.js - 2.57 KB
    └───/removeChildrenByType
      └───index.d.ts - 3.71 KB
      └───index.js - 5.63 KB
    └───/typeOfComponent
      └───index.d.ts - 614 Bytes
      └───index.js - 1.75 KB
      └───types.d.ts - 249 Bytes
      └───types.js - 79 Bytes
    └───/_private
      └───utils.d.ts - 61 Bytes
      └───utils.js - 913 Bytes
  └───/es6
    └───/getChild
      └───index.d.ts - 1.23 KB
      └───index.js - 1.63 KB
    └───/getChildByType
      └───index.d.ts - 4.16 KB
      └───index.js - 5.78 KB
    └───/getChildren
      └───index.d.ts - 1.21 KB
      └───index.js - 1.87 KB
    └───/getChildrenByType
      └───index.d.ts - 3.86 KB
      └───index.js - 5.12 KB
    └───/getChildrenWithDescendant
      └───index.d.ts - 638 Bytes
      └───index.js - 1.13 KB
    └───/getChildrenWithDescendantByType
      └───index.d.ts - 2.26 KB
      └───index.js - 2.81 KB
    └───/getDescendantDepth
      └───index.d.ts - 1.14 KB
      └───index.js - 2.3 KB
    └───/getDescendantDepthByType
      └───index.d.ts - 2.39 KB
      └───index.js - 3.74 KB
      └───index.d.ts - 1.1 KB
      └───index.js - 905 Bytes
    └───/noEmptyChildren
      └───index.d.ts - 1.75 KB
      └───index.js - 3.2 KB
    └───/overrideProps
      └───index.d.ts - 2.72 KB
      └───index.js - 4.44 KB
    └───/removeChildren
      └───index.d.ts - 1.22 KB
      └───index.js - 2.34 KB
    └───/removeChildrenByType
      └───index.d.ts - 3.71 KB
      └───index.js - 5.32 KB
    └───/typeOfComponent
      └───index.d.ts - 614 Bytes
      └───index.js - 1.6 KB
      └───types.d.ts - 249 Bytes
      └───types.js - 12 Bytes
    └───/_private
      └───utils.d.ts - 61 Bytes
      └───utils.js - 700 Bytes