feat(Avatar): add deterministic auto color

[EvanSchleret]

🔗 Linked issue

Resolves #6808

❓ Type of change

• 📖 Documentation (updates to the documentation or readme)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

Add an opt-in color="auto" option to UAvatar.

When enabled, the avatar background color is deterministically generated from the text or alt prop using an HSL hue derived from the characters of the avatar identity.

The generated color:

• Is stable across renders and server-side rendering
• Applies to fallback content only
• Supports UAvatarGroup
• Preserves explicit inline styles
• Keeps the existing behavior unchanged by default

Documentation, component tests, and snapshots have been updated accordingly.

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing EvanSchleret:feat/avatar-deterministic-background-color (923c743) with v4 (6add5fb)}

[pkg-pr-new]

npm i https://pkg.pr.new/@nuxt/ui@6810

commit: 923c743

[coderabbitai]

📝 Walkthrough

Walkthrough

The Avatar component now supports color: 'auto'. When fallback content is displayed, it derives a deterministic HSL background from the avatar text or alt value. Explicit background styles remain unchanged. Avatar and avatar-group themes define the new color variant. Tests cover deterministic colors and explicit style precedence. Documentation includes the new option and an example.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the Avatar feature and the deterministic auto color behavior.
Description check	✅ Passed	The description directly explains the new auto color option, its behavior, supported components, and related documentation and tests.
Linked Issues check	✅ Passed	The changes implement the opt-in auto color API, deterministic fallback styling, inline style precedence, default compatibility, contrast styling, and AvatarGroup support.
Out of Scope Changes check	✅ Passed	All reviewed changes support the linked issue by updating Avatar behavior, themes, documentation, and tests.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

src/runtime/components/Avatar.vue

Parsing error: Unexpected token )

src/theme/avatar-group.ts

Parsing error: Unexpected token {

src/theme/avatar.ts

Parsing error: Unexpected token {

• 1 others

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

test/components/Avatar.spec.ts (1)

42-63: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add coverage for the remaining fallback paths.

The tests cover alt without src and explicit style precedence. Add cases for text, UAvatarGroup color inheritance, and a failed src. These paths are part of the new behavior and would detect regressions in useAvatarGroup propagation and onError fallback handling.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/components/Avatar.spec.ts` around lines 42 - 63, Add tests covering the
remaining Avatar fallback paths alongside the existing auto-color cases: verify
color generation from text, color inheritance when Avatar is rendered inside
UAvatarGroup, and fallback behavior after the image src fails via onError. Reuse
the established mounting and assertion patterns, and ensure the tests detect
both useAvatarGroup propagation and failed-src fallback behavior.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@test/components/Avatar.spec.ts`:
- Around line 42-63: Add tests covering the remaining Avatar fallback paths
alongside the existing auto-color cases: verify color generation from text,
color inheritance when Avatar is rendered inside UAvatarGroup, and fallback
behavior after the image src fails via onError. Reuse the established mounting
and assertion patterns, and ensure the tests detect both useAvatarGroup
propagation and failed-src fallback behavior.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bfd42021-ff9f-4a36-a497-9b7bb4243116

📥 Commits

Reviewing files that changed from the base of the PR and between 6add5fb and 923c743.

⛔ Files ignored due to path filters (4)

• test/components/__snapshots__/Avatar-vue.spec.ts.snap is excluded by !**/*.snap
• test/components/__snapshots__/Avatar.spec.ts.snap is excluded by !**/*.snap
• test/components/__snapshots__/AvatarGroup-vue.spec.ts.snap is excluded by !**/*.snap
• test/components/__snapshots__/AvatarGroup.spec.ts.snap is excluded by !**/*.snap

📒 Files selected for processing (5)

• docs/content/docs/2.components/avatar.md
• src/runtime/components/Avatar.vue
• src/theme/avatar-group.ts
• src/theme/avatar.ts
• test/components/Avatar.spec.ts