> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/preactjs/preact/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```typescript theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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.

```jsx theme={null}
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:

```javascript theme={null}
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

```jsx theme={null}
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

```jsx theme={null}
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

```jsx theme={null}
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

```jsx theme={null}
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

```jsx theme={null}
// 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

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

### Direct Render

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

## With TypeScript

Type the children parameter:

```tsx theme={null}
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