docs: behavior state hooks RFC #35623

dmytrokirpa · 2026-01-07T11:04:29Z

What’s in this PR

This PR adds the RFC “Component Behavior State Hooks” as a separate proposal.

It is extracted from the broader “RFC: Unstyled Components” work in #35464, so reviewers can discuss the behavior-state-hooks proposal independently of the other changes in that PR.

The original PR also contains additional context and illustrative examples (including related patterns explored alongside unstyled components). If you want to see the broader exploration and code samples, refer to the linked PR.

What’s not in this PR

No implementation changes; this is documentation/RFC only.

github-actions · 2026-01-07T11:10:02Z

📊 Bundle size report

✅ No changes found

github-actions · 2026-01-07T11:10:32Z

Pull request demo site: URL

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md

layershifter · 2026-01-07T12:14:17Z

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md

+
+### Can I mix behavior state hooks with styled components?
+
+Yes! You can use behavior state hooks for some components and styled components for others in the same application. Keep in mind you'll need to provide styles when using behavior state hooks.


Suggested change

Yes! You can use behavior state hooks for some components and styled components for others in the same application. Keep in mind you'll need to provide styles when using behavior state hooks.

Yes.

> [!NOTE]

> We recommend to stick to a single option in your application to avoid UI misalignments.

You can use behavior state hooks for some components and styled components for others in the same application. Keep in mind you'll need to provide styles when using behavior state hooks.

lets make this suggestion as required rather "suggested change" as it's critical piece of information

Why do you feel it needs to be required? You can still use it that way, and there’s already a note with recommendations and implications. Making it “required” sounds like we’re saying you can’t mix different approaches, which is not technically correct to say

I don't think we should make it required (maybe strongly suggested?). My reason is that I think we ultimately need to be able to support a migration path if folks have an app with the existing, styled Fluent components and want to move to behavior hooks. I don't think we need to have this 100% sorted out now, just need to leave the door open for it.

layershifter · 2026-01-07T12:21:40Z

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md

+### Why the `_unstable` suffix?
+
+The `_unstable` suffix is consistent with Fluent UI's convention for hooks. While behavior state hooks are meant to be used in production, the suffix indicates they're lower-level primitives whose implementation details may evolve.
+


IMO there should be Out of scope section that covers render functions. I see that they are used in the example above, but as we discussed components that use portals might be challenging.

### Out of scope #### Render functions Base hooks provide only behavior (state, accessibility handling, etc.) while to build actual components you will also need render functions to product markup. Our general recommendation at the moment is to re-use existing render functions rather then implementing custom. We are going to provide more guidance in the future RFC for Unstyled components.

??

Aside: hopefully we can minimize the need for portals as things like Popover API and CSS anchor positioning get better support.

Hotell · 2026-01-07T14:05:50Z

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md

+Introduce behavior state hooks per component using the naming pattern `use${ComponentName}Base_unstable`:
+
+```tsx
+import { useButtonBase_unstable } from '@fluentui/react-components';


for pilot testing/usage I think we discussed to stick with per-package only ?

I'm open to feedback on this - both options should work. If no one has strong arguments or pushback against it, we can go ahead and add it to the suite too.

@khmakoto Do you have an opinion here?

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md

Hotell · 2026-01-07T14:16:50Z

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md

+  const { appearance = 'secondary', size = 'medium', shape = 'rounded' } = props;
+
+  return {
+    ...useButtonBase_unstable(props, ref),


briefly touched offline, but have we thought about how we will enforce that the "proper" logic lives in the proper domain -> base vs non base?

this might be crucial to not deviate from the domain of the behaviour hook

We don’t really enforce anything with existing state hooks - for example, everyone agrees not to put Griffel styles in a state hook, but there’s no actual rule about it. So, what makes you think we should enforce it in this case?

Hotell · 2026-01-07T14:18:39Z

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md

+
+## Usage Example
+
+Building a custom button with your own design system:


might be worth to actually provide "Real example" containing custom provider and tokens ( as we are mentioning "design system" )

I intentionally didn't add that, as I want to avoid 20+ comments about personal opinions on how it should be written/implemented 😄. I'd leave this for users to decide how to setup tokens and as it really depends on the styling approach.

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md

Hotell · 2026-01-07T14:36:55Z

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md

+
+### Do behavior state hooks guarantee accessibility?
+
+Behavior state hooks provide correct ARIA attributes, keyboard handling, and semantic structure. However, **you're responsible for ensuring custom styles don't interfere with accessibility (e.g., sufficient contrast, visible focus indicators).**


could this be provided as lint rules/conformance test suite for these adopters to make sure a11y is not broken when they decide to use this api ?

that's a good point, but tbh I'm not sure we're in a position/have capacity for this. and also don't think we should, we definitely should provide a guidance/recommendation, but we can't enforce something that is beyond of ours control.

Hotell · 2026-01-07T14:39:19Z

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md

+
+### Can I mix behavior state hooks with styled components?
+
+Yes! You can use behavior state hooks for some components and styled components for others in the same application. Keep in mind you'll need to provide styles when using behavior state hooks.


lets make this suggestion as required rather "suggested change" as it's critical piece of information

spmonahan · 2026-01-07T21:50:46Z

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md

+```tsx
+import { useButtonBase_unstable } from '@fluentui/react-components';
+// or from the package directly
+import { useButtonBase_unstable } from '@fluentui/react-button';


Based on the name of this RFC I'll suggest these hooks might be named use$ComponentNameBehavior_unstable --> useButtonBehavior_unstable.

One of the other main things we'd need to remove in the use$ComponentNameBehavior_unstable hooks would be things like tabster (useArrowNavigationGroup, etc.).

imo I'd expect that to be included in the "Behaviour" hook based on the name but would need to be excluded in practice.

Blurs the line a bit with a11y too as often the keyboarding model would be considered part of that but we'd actively want to exclude it from this new hook

One of the other main things we'd need to remove in the use$ComponentNameBehavior_unstable hooks would be things like tabster (useArrowNavigationGroup, etc.).

imo I'd expect that to be included in the "Behaviour" hook based on the name but would need to be excluded in practice.

Blurs the line a bit with a11y too as often the keyboarding model would be considered part of that but we'd actively want to exclude it from this new hook

That’s not going to work for this version since tabster is still pretty important for the a11y setup. We can’t just leave it out of the hook right now. We should put together a separate proposal and tackle it on its own. We're also still need to figure out if we want to drop/replace it, or maybe just make it lazy-loadable.

spmonahan · 2026-01-07T22:05:51Z

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md

+
+### What about accessibility-critical inline styles?
+
+Default behavior state hooks should not apply styles. The exception is when a specific CSS property is required for accessibility or core functionality (and is currently implemented via Griffel styles). In those cases, apply the minimum inline style needed and document the rationale.


In those cases, apply the minimum inline style needed and document the rationale.
Will this create specificity problems? Inline styles have fairly high specificity.

Perhaps it won't much matter in practice as I imagine overriding these styles is generally a bad idea but I think we should have an example of how an override might work here.

spmonahan · 2026-01-07T22:09:37Z

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md

+Yes. You can use behavior state hooks for some components and styled components for others in the same application.
+
+> [!NOTE]
+> We recommend sticking to a single option in your application to avoid UI misalignments.


Agree with this recommendation but I think we should have a notion of what it looks like for an app to migrate from styled Fluent to behavior state hooks.

layershifter · 2026-01-08T09:23:25Z

@dmytrokirpa in offline we discussed risks of shipping new hooks in the stable packages.

Let's add a section to the RFC about our promises on breaking changes for these hooks.
Let's clarify exports (export from the suite or no) & naming parts.

I don't have strong opinions on this (except that we shouldn't re-export them from the suite package from day 1), so feel free to propose options based on the discussion yesterday.

dmytrokirpa · 2026-01-08T13:48:03Z

@dmytrokirpa in offline we discussed risks of shipping new hooks in the stable packages.

Let's add a section to the RFC about our promises on breaking changes for these hooks.

Let's clarify exports (export from the suite or no) & naming parts.

I don't have strong opinions on this (except that we shouldn't re-export them from the suite package from day 1), so feel free to propose options based on the discussion yesterday.

@layershifter Updated the behavior-state-hooks RFC with several key changes:

1. Naming Convention Change:

Renamed from use${ComponentName}Base_unstable → use${ComponentName}Behavior_unstable
Updated type names: ButtonBaseProps/State → ButtonBehaviorProps/State
Rationale: "Behavior" more clearly describes what these hooks provide (behavior without styling)
Updated throughout all code examples, diagrams, and references

2. Exports and Naming Section (new):

Behavior state hooks exported from individual component packages (e.g., @fluentui/react-button)
NOT re-exported from suite package (@fluentui/react-components) initially
Establishes clear naming pattern for hooks, props, and state types
May consider suite re-export in future based on adoption

3. Release Strategy Section (new):

Feature branch development: Iterate without blocking main branch
Experimental releases: Individual component packages with experimental tags (e.g., @fluentui/react-button@experimental)
Partner validation: Gather feedback before stabilizing
Benefits: Early access, API refinement, stable releases unaffected, incremental rollout
Stability guarantees: Once stable, follows standard _unstable API guarantees (implementation details may change in minor versions, public API follows semver)

Commit: 52a0480

change

6b3b257

dmytrokirpa self-assigned this Jan 7, 2026

github-actions bot added the Type: RFC Request for Feedback label Jan 7, 2026

docs(rfc): add behavior state hooks

948a0d2

dmytrokirpa force-pushed the rfc/behavior-state-hooks branch from 227bbb8 to 948a0d2 Compare January 7, 2026 11:05

dmytrokirpa marked this pull request as ready for review January 7, 2026 11:08

dmytrokirpa requested review from a team as code owners January 7, 2026 11:08

dmytrokirpa added the Fluent UI react-components (v9) label Jan 7, 2026

dmytrokirpa mentioned this pull request Jan 7, 2026

RFC: Unstyled Components #35464

Closed

layershifter reviewed Jan 7, 2026

View reviewed changes

docs/react-v9/contributing/rfcs/react-components/convergence/behavior-state-hooks.md Outdated Show resolved Hide resolved

layershifter reviewed Jan 7, 2026

View reviewed changes

tudorpopams requested review from Hotell and mainframev January 7, 2026 13:05

apply review suggestions

82bd448

dmytrokirpa force-pushed the rfc/behavior-state-hooks branch from 26542d6 to 82bd448 Compare January 7, 2026 14:30

Merge branch 'master' into rfc/behavior-state-hooks

5b7fc22

Hotell reviewed Jan 7, 2026

View reviewed changes

more comments

c0cd682

spmonahan reviewed Jan 7, 2026

View reviewed changes

upd

52a0480

update development and release process

3aad2b0

layershifter approved these changes Jan 9, 2026

View reviewed changes


		### Can I mix behavior state hooks with styled components?

		Yes! You can use behavior state hooks for some components and styled components for others in the same application. Keep in mind you'll need to provide styles when using behavior state hooks.

		### Why the `_unstable` suffix?

		The `_unstable` suffix is consistent with Fluent UI's convention for hooks. While behavior state hooks are meant to be used in production, the suffix indicates they're lower-level primitives whose implementation details may evolve.


		## Usage Example

		Building a custom button with your own design system:


		### Do behavior state hooks guarantee accessibility?

		Behavior state hooks provide correct ARIA attributes, keyboard handling, and semantic structure. However, you're responsible for ensuring custom styles don't interfere with accessibility (e.g., sufficient contrast, visible focus indicators).


		### What about accessibility-critical inline styles?

		Default behavior state hooks should not apply styles. The exception is when a specific CSS property is required for accessibility or core functionality (and is currently implemented via Griffel styles). In those cases, apply the minimum inline style needed and document the rationale.

docs: behavior state hooks RFC #35623

Are you sure you want to change the base?

docs: behavior state hooks RFC #35623

Conversation

dmytrokirpa commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What’s in this PR

What’s not in this PR

Uh oh!

github-actions bot commented Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📊 Bundle size report

Uh oh!

github-actions bot commented Jan 7, 2026

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmytrokirpa Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

dmytrokirpa Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

layershifter commented Jan 8, 2026

Uh oh!

dmytrokirpa commented Jan 8, 2026

1. Naming Convention Change:

2. Exports and Naming Section (new):

3. Release Strategy Section (new):

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

dmytrokirpa commented Jan 7, 2026 •

edited

Loading

github-actions bot commented Jan 7, 2026 •

edited

Loading

dmytrokirpa Jan 7, 2026 •

edited

Loading

dmytrokirpa Jan 7, 2026 •

edited

Loading