[field][avatar] Add transition attributes

[atomiks]

• I have followed (at least) the PR section of the contributing guide.

Closes #3921

Also fixes a bug where <Checkbox.Indicator> and <Radio.Indicator> didn't allow exit animations when keepMounted=false

https://deploy-preview-3939--base-ui.netlify.app/experiments/transition-attrs

[pkg-pr-new]

• base-ui-tanstack-start

• vite-css-base-ui-example

  pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/react@3939
  

  pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/utils@3939
  

commit: 2cba972

[mui-bot]

Bundle size report

Bundle	Parsed size	Gzip size
@base-ui/react	🔺+825B(+0.20%)	🔺+236B(+0.18%)

Details of bundle changes

---

Check out the code infra dashboard for more information about this PR.

[netlify]

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	2cba972
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/698d111a46e1d8000868ef2d
😎 Deploy Preview	https://deploy-preview-3939--base-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds transition attributes support to Field.Error, Avatar.Image, and Avatar.Fallback components, enabling smooth enter and exit animations. It also fixes a bug where Checkbox.Indicator and Radio.Indicator didn't allow exit animations when keepMounted=false.

Key Changes

• Field.Error: Added transitionStatus to state and useTransitionStatus/useOpenChangeComplete hooks for managing mount/unmount lifecycle during transitions. Implemented message caching to prevent content changes during exit animations.
• Avatar.Image & Avatar.Fallback: Added transition state management with proper visibility tracking and data-starting-style/data-ending-style attributes.
• Checkbox.Indicator & Radio.Indicator: Fixed bug by using mounted state from useTransitionStatus instead of rendered flag, allowing proper exit animations when keepMounted=false.
• Tests: Comprehensive animation tests added for all affected components, verifying enter/exit animations work correctly in browser environments.
• E2E Tests: Updated to query specific error messages instead of generic error element, improving test reliability with the new transition behavior.
• Type Definitions: Updated generated JSON docs to use component-specific state types instead of root state types.

The implementation follows established patterns in the codebase and includes proper test coverage.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation is well-structured with comprehensive test coverage, follows established codebase patterns, and fixes a documented bug while adding new functionality
• No files require special attention

Important Files Changed

Filename	Overview
packages/react/src/field/error/FieldError.tsx	Added transition attributes support to Field.Error component with proper state management for exit animations
packages/react/src/avatar/fallback/AvatarFallback.tsx	Added transition attributes support to Avatar.Fallback component with mounted state tracking
packages/react/src/avatar/image/AvatarImage.tsx	Added transition attributes support to Avatar.Image with loading state handling
packages/react/src/checkbox/indicator/CheckboxIndicator.tsx	Fixed keepMounted=false bug by properly using mounted state instead of rendered for exit animations
packages/react/src/radio/indicator/RadioIndicator.tsx	Fixed keepMounted=false bug by properly using mounted state instead of rendered for exit animations

[mj12albert]

Transition support would be useful for Field.Validity as well (e.g. animating a validity status indicator/svg) though it's a bit different

also an experiments nit: could maybe just add transitions to existing experiments (e.g. for checkbox, field error) instead of making an all new one ~

[atomiks]

Transition support would be useful for Field.Validity as well (e.g. animating a validity status indicator/svg) though it's a bit different

Yeah, the issue is <Field.Validity> doesn't render its own element to add the attributes onto

also an experiments nit: could maybe just add transitions to existing experiments (e.g. for checkbox, field error) instead of making an all new one ~

I intentionally left off accordion, collapsible, and popups for this demo since they have their own, but checkbox/radio/avatar etc. don't so I just made a single demo for them all together

[mj12albert]

Does it make sense to add transitionStatus to the state called by the children render fn?

[atomiks]

@mj12albert yeah it's possible to add as part of the argument passed so children can use it (added demo with it)

The main issue is you can't unmount the children since there's no control over setMounted(false) or the ref to detect animations on. As a result transitionStatus stays as 'ending' and the children are kept mounted. I suppose that's okay for simple trees, though

[mnajdova]

Please update the PR title and labels to include all components that have updates so the changelog can be generated correctly.

[atomiks]

Please update the PR title and labels to include all components that have updates so the changelog can be generated correctly.

Yeah the issue is that checkbox/radio were drive-by changes here, they'll need to be split into "bug fixes" when writing release notes @flaviendelangle

[wishyoudie]

There seems to be an issue with displaying avatar fallback after these changes (on v1.2.0). If I understood correctly, AvatarImage now shows while the image is loading this line, but AvatarFallback can also be shown at the same time in low network conditions when delayPassed is true: this line. This results in both being displayed at the same time causing visual glitches when overflow is not set to hidden on Root.

[atomiks]

@wishyoudie thanks for the report, can you make a new issue with a reproduction?

[wishyoudie]

@atomiks Thank you for quick reply. Filed #4109.