RFC: Headless Components (@fluentui/react-headless-components)#35984
Open
dmytrokirpa wants to merge 4 commits intomicrosoft:masterfrom
Open
RFC: Headless Components (@fluentui/react-headless-components)#35984dmytrokirpa wants to merge 4 commits intomicrosoft:masterfrom
dmytrokirpa wants to merge 4 commits intomicrosoft:masterfrom
Conversation
Proposes `@fluentui/react-headless` — unstyled components built from base state hooks and render functions, with stable `data-*` attributes as the CSS-targeting contract for component state. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
📊 Bundle size report✅ No changes found |
|
Pull request demo site: URL |
dmytrokirpa
changed the title
dmytrokirpa
force-pushed
the
dmytrokirpa/rfc-headless-components
branch
from
7d11b15 to
4e58ed7
Compare
Hotell
reviewed
Apr 13, 2026
| Headless components include: | ||
|
|
||
| - behavior and ARIA from base hooks | ||
| - existing slot API |
Contributor
There was a problem hiding this comment.
we should highlight info about default slots ( no icons etc )
| Ship headless components from `@fluentui/react-headless-components`. | ||
|
|
||
| ```tsx | ||
| import { Button, Checkbox } from '@fluentui/react-headless-components'; |
Contributor
There was a problem hiding this comment.
should highlight the export maps api only
| ``` | ||
|
|
||
| This abstraction preserves the existing base architecture but removes repetitive wiring from app | ||
| code. Note: headless components wrap existing hooks — they introduce no new behavior or |
Contributor
There was a problem hiding this comment.
lets improve the structure
Suggested change
| code. Note: headless components wrap existing hooks — they introduce no new behavior or | |
| code. | |
| > **💁♂️ Note:** headless components wrap existing hooks — they introduce no new behavior or |
|
|
||
| ### State To `data-*` Mapping (Primary Contract) | ||
|
|
||
| Headless state hooks map internal state to stable `data-*` attributes. Components then render |
Contributor
There was a problem hiding this comment.
might be good to note that this pattern is also used for icons headless
| - no design-state attributes (no appearance/size/shape) | ||
| - removal/rename is breaking (major) | ||
| - adding a new attribute is non-breaking for CSS selectors; it may affect snapshot tests, which is acceptable | ||
| - data attributes must be documented on the components documentation page (Storybook docsite) |
Contributor
There was a problem hiding this comment.
it would be actually good to have these as part of State type, then this will be part of .d.ts -> easy agent metadata extraction / SB table enablement
Comment on lines
+35
to
+36
| Use headless when teams need Fluent behavior with non-Fluent visuals. | ||
| Use styled components when teams want Fluent visuals with branding tweaks. |
Contributor
There was a problem hiding this comment.
this probably doesn't have to be part of this RFC, as the goal is clearly set above
- Clarify slot API: root slot only by default; optional slots (icon, avatar, indicator) require explicit props - Remove redundant use-case guidance (already covered by Goal section) - Add note that only the export-map root is a supported import surface - Reformat composition-model note as a blockquote - Note that icon-state data attributes follow the same data-* pattern - Require data attributes to be typed on the State type for .d.ts / Storybook props-table / agent metadata extraction Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
|
||
| **[Radix UI](https://www.radix-ui.com/)** uses a single `data-state` attribute per component with semantic string values (`data-state="open"` / `"closed"` on Dialog, `data-state="checked"` / `"unchecked"` on Checkbox). Additional attributes like `data-disabled` and `data-highlighted` cover contextual state. | ||
|
|
||
| **[React Aria Components](https://react-spectrum.adobe.com/react-aria/react-aria-components.html)** (Adobe) emits granular per-property `data-*` attributes (`data-hovered`, `data-pressed`, `data-focused`, `data-focus-visible`, `data-disabled`, `data-selected`, `data-orientation`, etc.). It also supports render props as an alternative — consumers can pass a function to `className` or `style` that receives the full component state object. |
Contributor
There was a problem hiding this comment.
Do you need so many examples of data-attributes? Probably 3 would be enough before "etc"
ValentinaKozlova
approved these changes
Apr 17, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Proposes
@fluentui/react-headless— a package of unstyled components built from base state hooks and render functions, with stabledata-*attributes as the CSS-targeting contract for component state.This is the next layer above the Base State Hooks RFC.
What's in this RFC
@fluentui/react-headlessas a single import surface re-exporting base hooks from individual packagesdata-*attribute schema on root slots, emitted by both headless and styled variantsRelated