Never Post Memes

    react-nanny
    TypeScript icon, indicating that this package has built-in type declarations

    2.15.0 • Public • Published

    Build Status Coverage Status

    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

    Install

    npm i react-nanny

    DownloadsWeekly Downloads

    7,865

    Version

    2.15.0

    License

    MIT

    Unpacked Size

    155 kB

    Total Files

    68

    Last publish

    Collaborators

    • paravano