Composition

Learn how to compose components in Chakra UI.

The `as` Prop

Used to change the underlying HTML element that a React component renders. It provides a straightforward way to change the underlying element while retaining the component's functionality.

<Heading as="h3">Hello, world!</Heading>

warning

TypeScript: The caveat with the as prop is that the types of the component passed to the as prop must be compatible with the component's props. We do not infer the underlying component's props from the as prop.

The `asChild` Prop

Used to compose a component's functionality onto its child element. This approach, inspired by Radix UI, offers maximum flexibility.

<Popover.Root>
  <Popover.Trigger asChild>
    <Button>Open</Button>
  </Popover.Trigger>
</Popover.Root>

In this example, the asChild prop allows the Button to be used as the trigger for the popover.

Best Practices

To avoid common pitfalls when using the as and asChild props, there are a few best practices to consider:

Forward Refs: Ensure that the underlying component forwards the ref passed to it properly.
Spread Props: Ensure that the underlying component spreads the props passed to it.

const MyComponent = React.forwardRef((props, ref) => {
  return <Box ref={ref} {...props} />
})

// with `as` prop
<MyComponent as="button" />

// with `asChild` prop
<Button asChild>
  <MyComponent> Click me </MyComponent>
</Button>

Overview

Animation

Composition

The asChild Prop

Best Practices

The `asChild` Prop