Children

Utilities for working with the children prop in Preact components

Children

Utilities for manipulating and transforming the children prop. This API is mostly unnecessary in Preact but provided for React compatibility.

API

const Children: {
  map<T, R>(
    children: T | T[],
    fn: (child: T, i: number) => R,
    context?: any
  ): R[];
  
  forEach<T>(
    children: T | T[],
    fn: (child: T, i: number) => void,
    context?: any
  ): void;
  
  count(children: ComponentChildren): number;
  
  only(children: ComponentChildren): ComponentChild;
  
  toArray(children: ComponentChildren): VNode<{}>[];
}

Methods

Children.map

Transform each child and return a new array.

import { Children } from 'preact/compat';

function AddProps({ children }) {
  return (
    <div>
      {Children.map(children, (child, index) => (
        // Clone each child and add a className
        <child.type {...child.props} className="mapped-child" key={index} />
      ))}
    </div>
  );
}

// Usage
<AddProps>
  <div>First</div>
  <div>Second</div>
  <div>Third</div>
</AddProps>

Children.forEach

Iterate over children without returning anything.

import { Children } from 'preact/compat';

function LogChildren({ children }) {
  Children.forEach(children, (child, index) => {
    console.log(`Child ${index}:`, child);
  });
  
  return <div>{children}</div>;
}

// Usage
<LogChildren>
  <span>One</span>
  <span>Two</span>
</LogChildren>

Children.count

Count the number of children.

import { Children } from 'preact/compat';

function ShowCount({ children }) {
  const count = Children.count(children);
  
  return (
    <div>
      <p>Number of children: {count}</p>
      {children}
    </div>
  );
}

// Usage
<ShowCount>
  <div>One</div>
  <div>Two</div>
  <div>Three</div>
</ShowCount>
// Shows: "Number of children: 3"

Children.only

Verify that children contains only one child and return it. Throws an error if there are multiple children.

import { Children } from 'preact/compat';

function SingleChild({ children }) {
  // Throws if more than one child
  const child = Children.only(children);
  
  return <div className="wrapper">{child}</div>;
}

// Valid usage
<SingleChild>
  <span>Only child</span>
</SingleChild>

// Invalid usage - throws error
<SingleChild>
  <span>First</span>
  <span>Second</span>
</SingleChild>

Children.toArray

Convert children to a flat array of VNodes.

import { Children } from 'preact/compat';

function FlattenChildren({ children }) {
  const childArray = Children.toArray(children);
  
  return (
    <ul>
      {childArray.map((child, index) => (
        <li key={index}>{child}</li>
      ))}
    </ul>
  );
}

// Usage
<FlattenChildren>
  <span>One</span>
  {['Two', 'Three']}
  <span>Four</span>
</FlattenChildren>
// Flattens to 4 items

Implementation Details

The Children implementation in Preact:

import { toChildArray } from 'preact';

const mapFn = (children, fn, context) => {
  if (children == null) return null;
  return toChildArray(toChildArray(children).map(fn.bind(context)));
};

export const Children = {
  map: mapFn,
  forEach: mapFn,
  count(children) {
    return children ? toChildArray(children).length : 0;
  },
  only(children) {
    const normalized = toChildArray(children);
    if (normalized.length !== 1) throw 'Children.only';
    return normalized[0];
  },
  toArray: toChildArray
};

Key Features

1. Null Handling: Safely handles null or undefined children
2. Flattening: Uses toChildArray from Preact core to flatten nested arrays
3. Context Binding: Supports binding a context object for map and forEach
4. Validation: only throws an error if multiple children are present

Common Use Cases

Adding Props to All Children

import { Children, cloneElement } from 'preact/compat';

function EnhanceChildren({ children, extraProp }) {
  return (
    <div>
      {Children.map(children, child => 
        cloneElement(child, { extraProp })
      )}
    </div>
  );
}

// Usage
<EnhanceChildren extraProp="value">
  <Child1 />
  <Child2 />
</EnhanceChildren>

Filtering Children

import { Children } from 'preact/compat';

function FilterChildren({ children, filterType }) {
  const filtered = Children.toArray(children).filter(
    child => child.type === filterType
  );
  
  return <div>{filtered}</div>;
}

// Usage
function Button() { return <button>Click</button>; }
function Link() { return <a href="#">Link</a>; }

<FilterChildren filterType={Button}>
  <Button />
  <Link />
  <Button />
</FilterChildren>
// Only renders Button components

Conditional Rendering

import { Children } from 'preact/compat';

function ShowIfMultiple({ children, fallback }) {
  const count = Children.count(children);
  
  if (count < 2) {
    return fallback || <div>Need at least 2 children</div>;
  }
  
  return <div>{children}</div>;
}

Wrapping Each Child

import { Children } from 'preact/compat';

function WrapChildren({ children, wrapper: Wrapper }) {
  return (
    <>
      {Children.map(children, (child, index) => (
        <Wrapper key={index}>{child}</Wrapper>
      ))}
    </>
  );
}

// Usage
<WrapChildren wrapper={({ children }) => <div className="item">{children}</div>}>
  <span>One</span>
  <span>Two</span>
  <span>Three</span>
</WrapChildren>
// Each child is wrapped in a div.item

When NOT to Use Children

In most cases, you don’t need the Children API in Preact:

Direct Array Methods

// Instead of Children.map:
function Component({ children }) {
  return <div>{children}</div>;
}

// Or use array methods directly if needed:
function Component({ items }) {
  return (
    <div>
      {items.map((item, i) => <Item key={i} {...item} />)}
    </div>
  );
}

Array.isArray Check

// Instead of Children.count:
function Component({ children }) {
  const count = Array.isArray(children) ? children.length : children ? 1 : 0;
  return <div>Count: {count}</div>;
}

Direct Render

// Instead of Children.toArray:
function Component({ children }) {
  // Preact handles arrays automatically
  return <div>{children}</div>;
}

With TypeScript

Type the children parameter:

import { Children, ComponentChildren, ComponentChild } from 'preact/compat';

interface Props {
  children: ComponentChildren;
}

function Component({ children }: Props) {
  const count = Children.count(children);
  
  return (
    <div>
      <p>Count: {count}</p>
      {children}
    </div>
  );
}

Performance Considerations

1. Overhead: Children methods add overhead - avoid if not needed
2. Direct Arrays: Use array methods directly when possible
3. Keys: Always provide keys when using Children.map
4. Immutability: Children.map creates new arrays - be mindful in hot paths

Best Practices

1. Prefer Direct Rendering: Use {children} directly when possible
2. Type Safety: Use TypeScript for better type checking
3. Keys: Always provide keys when mapping children
4. Validation: Use Children.only for components expecting single children
5. Error Handling: Handle the case when Children.only throws

Comparison with React

Preact’s Children API is compatible with React’s, but simpler:

• No Children.map context parameter in Preact: The third parameter is supported but rarely used
• Simpler implementation: Built on top of Preact’s toChildArray
• Full compatibility: Works with React code expecting the Children API

Source

Implementation: compat/src/Children.js:1-22