Expose aria-labelledby / aria-describedby attributes for form controls

[PavelZhuravlev]

Hey, thanks for maintaining such a great package!

I just wanted to share a small improvement request for review.

Context:

Currently, access to the mentioned attributes is hidden from the consumer in favor of using the compositional Field, Label, and Description components. While the proposed composition works well and approaches the task in a more declarative way, in the context of integrating Headless UI components into an existing ecosystem, it might be too opinionated and promote unwanted inconsistency with existing approaches - especially for a headless library.

The existing application might already have an established mechanism to associate components with their corresponding accessible name/description pair. That solution might rely on injecting these attributes into component props, either via a render prop or context.

However, Headless UI components, like Checkbox, don’t allow passing these props directly and instead enforce a “different” way of doing things. This enforcement promotes inconsistency within the application’s design system, which is supposed to unify components from different libraries under a single ecosystem.

Example:

// custom component
<FormField label="My label" render={(props) => <CustomInput aria-labelledby={props.labelId} />} />

// native component
<FormField label="My label" render={(props) => <textarea aria-labelledby={props.labelId} />} />

// headlessui -  not possible
<FormField label="My label" render={(props) => <Checkbox aria-labelledby={props.labelId} />} />

// headlessui -  promotes inconsistency, conflicts with existing mechanism
<Field>
 <FormField label={<Label>My label</Label>} render={(props) => <Checkbox />} />
</Field>

While I appreciate the compositional approach the library offers, the lack of support for the default props API makes it difficult to integrate with existing solutions and causes Headless UI components to stand out from the rest of the ecosystem. From a design perspective, it forces the system to adapt to the library’s approach, rather than the other way around. It may also violate the LSP, preventing interchangeable use of different implementations of base form controls.

Proposal:

To address the mentioned issue and provide alternatives, while still supporting and promoting the suggested compositional approach, the library could expose aria-labelledby and aria-describedby attributes. Directly provided props should take precedence over those derived from the Field / Label / Description context linkage. Giving priority to direct props over context-derived ones is a logical and commonly used pattern when solving similar problems. This way, the existing declarative approach can complement the vanilla API, rather than making integration overly opinionated and forcing consumers to choose between consistency and the other features the library offers.

Thank you in advance!