docs(theme): note layer merging breaks function slot overrides

[lazerg]

🔗 Linked issue

Related to #6928

❓ 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

Nuxt merges the app.config.ts of every layer with defuFn. When a slot is set to a function and the same key already has a value lower down, another layer or appConfig in nuxt.config, defuFn calls that function during the merge and stores what it returns, so app.config.ui.<component>.slots.<slot> is already a plain string by the time Nuxt UI reads it. A string means merge, which is why the defaults come back instead of being replaced. With a single definition there is nothing under the function, it survives the merge untouched and the replace behaviour works as documented.

Nothing is left for Nuxt UI to detect once the merge has run, so this adds a warning next to the function form with the one thing that does work: keep the function in a single place. The issue stays open because the behaviour itself is unchanged. A marker object instead of a bare function (something like replace('...')) would go through the normal deep merge and survive any number of layers, so that would fix it properly, but it is an API addition. Happy to send that if you want it.

📝 Checklist

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 2c3b9043-3818-4180-8036-31daba26adbd

📥 Commits

Reviewing files that changed from the base of the PR and between 69281d2 and 1107e41.

📒 Files selected for processing (1)

• docs/content/docs/1.getting-started/5.theme/3.components.md

Included review availability: Your plan provides up to 8 included reviews per hour; 6 remain after this review.

---

📝 Walkthrough

Walkthrough

Added a Nuxt-only warning to the component theming documentation. The warning states that slot replacement functions must be defined in one layer. Functions defined in multiple Nuxt layers are resolved to strings before Nuxt UI reads them, so they merge with default classes instead of replacing them.

Estimated code review effort: 1 (Trivial) | ~2 minutes

Merge Risk: ⚪ Minimal · up to 1107e

The documentation now warns Nuxt users that defining function-based slot overrides in multiple layers causes class merging rather than replacement. This clarifies an existing limitation without changing runtime behavior, and no merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The documentation describes the issue and its workaround, but the reported behavior remains unfixed. The latest layer's function does not fully replace the default classes when multiple layers define …	Fix the multi-layer function override behavior so the latest layer's slot function fully replaces the component defaults, or provide explicit issue-level approval that documentation-only mitigation satisfies #6928.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	The only change adds documentation for the multi-layer function override behavior described in issue #6928. No unrelated changes are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Description check	✅ Passed	The description accurately explains the Nuxt layer-merging behavior, the defuFn interaction, and the documentation change.
Title check	✅ Passed	The title clearly identifies the documentation change and the issue with function-based slot overrides during layer merging.

Full details: Linked Issues check

Explanation

The documentation describes the issue and its workaround, but the reported behavior remains unfixed. The latest layer's function does not fully replace the default classes when multiple layers define the same slot, which is the expected behavior in issue #6928.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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.}

[codspeed]

Merging this PR will improve performance by 12.02%

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
✅ 30 untouched benchmarks

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
⚡	plain <button>	1.3 ms	1.2 ms	+12.02%

Tip

Curious why performance improved? Comment @codspeedbot explain why performance improved on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing lazerg:fix/issue-6928 (1107e41) with v4 (970025f)}

[pkg-pr-new]

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

commit: 1107e41