tailwindlabs/headlessui · error · Error

Passing props on "Fragment"! The current component <${name}

Q: What causes "Passing props on "Fragment"! The current component is rendering a "Fragment". However we need to passthrough the following props: - ${line} You can apply a few solutions: - Add an `as="..."` prop, to ensure that we render an actual element instead of a "Fragment". - Render a single element as the child so that we can forward the props onto that element." in tailwindlabs/headlessui?

Render a single element as the child (or the default `as` element) so props can be forwarded onto it.

Error message

Passing props on "Fragment"!

The current component <${name} /> is rendering a "Fragment".
However we need to passthrough the following props:
  - ${line}

You can apply a few solutions:
  - Add an `as="..."` prop, to ensure that we render an actual element instead of a "Fragment".
  - Render a single element as the child so that we can forward the props onto that element.

What it means

Headless UI's render() cannot forward DOM props (className, event handlers, ids, aria-*) onto a React Fragment, because Fragments accept no attributes. When a component is rendered `as={Fragment}` (or as a component returning a Fragment) and there are props to passthrough, or the child resolution produces multiple children or a fragment instance, this error is thrown to tell you the props would be silently dropped.

Source

Thrown at packages/@headlessui-react/src/utils/render.ts:197

    }

    if (exposeState) {
      dataAttributes['data-headlessui-state'] = states.join(' ')
      for (let state of states) {
        dataAttributes[`data-${state}`] = ''
      }
    }
  }

  if (isFragment(Component)) {
    if (Object.keys(compact(rest)).length > 0 || Object.keys(compact(dataAttributes)).length > 0) {
      if (
        !isValidElement(resolvedChildren) ||
        (Array.isArray(resolvedChildren) && resolvedChildren.length > 1) ||
        isFragmentInstance(resolvedChildren)
      ) {
        if (Object.keys(compact(rest)).length > 0) {
          throw new Error(
            [
              'Passing props on "Fragment"!',
              '',
              `The current component <${name} /> is rendering a "Fragment".`,
              `However we need to passthrough the following props:`,
              Object.keys(compact(rest))
                .concat(Object.keys(compact(dataAttributes)))
                .map((line) => `  - ${line}`)
                .join('\n'),
              '',
              'You can apply a few solutions:',
              [
                'Add an `as="..."` prop, to ensure that we render an actual element instead of a "Fragment".',
                'Render a single element as the child so that we can forward the props onto that element.',
              ]
                .map((line) => `  - ${line}`)
                .join('\n'),
            ].join('\n')

View on GitHub (pinned to eea57cf46f)

Solutions

Render a single element as the child (or the default `as` element) so props can be forwarded onto it.
Use a real element: as="div" (or as={MyComponent} that renders a real root element) instead of as={Fragment}.
If a custom component is used for `as`, make sure its root output is a single DOM element that spreads all incoming props onto it.

Example fix

// before
<Dialog as={Fragment} className="z-10"> {/* throws: props on Fragment */}
  <div>...</div>
</Dialog>

// after
<Dialog className="z-10">
  <div>...</div>
</Dialog>

Defensive patterns

Strategy: validation

Validate before calling

// Before rendering a Headless UI component with as={Fragment}, check what must be forwarded
const propsToForward = { className, onClick, 'data-testid': id } // etc.
if (Object.keys(propsToForward).length > 0 && asIsFragment) {
  // render a real element instead
  as = 'div'
}

Type guard

const isFragment = (as: unknown): as is React.Fragment => as === React.Fragment || as === Fragment

Try / catch

try { render } catch (e) { if (e instanceof Error && e.message.includes('Passing props on "Fragment"')) { /* re-render with as="div" */ } else throw e }

Prevention

Avoid as={Fragment} whenever you need to pass className, refs, ids, or event handlers.
When using as={Fragment}, provide exactly one child element that accepts and spreads the incoming props.
Ensure custom `as` components render a single root DOM element and forward all props onto it.

When it happens

Trigger: Using as={Fragment} on Menu.Button, Dialog.Panel, etc. while also passing className, onClick, data-* or ref; providing multiple children where a single child element is required; a custom `as` component whose root render is <></> while the Headless UI component needs to inject props.

Common situations: Trying to avoid an extra DOM element with as={Fragment} but still styling via className; wrapping the child in a fragment or comma-separated siblings; custom wrapper components that render fragments internally.

Related errors

AI-assisted analysis of tailwindlabs/headlessui@eea57cf46f (2026-08-28). Data as JSON: /api/errors/df2a46af9928b777. Report an issue: GitHub.