doc: document named slots in layouts via inline components

[Copilot]

Qwik City layouts can define multiple named <Slot name="..." /> areas, but pages exported as component$ create an opaque component boundary — the router passes the page as a single child, so q:slot attributes inside its rendered output are invisible to the layout's slot system.

The fix is to export the page as an inline component (plain function). Qwik's flatVirtualChildren/splitProjectedChildren (in render-ssr.ts) calls plain functions directly and flattens their JSX, making q:slot attributes visible to the parent layout.

Changes

• packages/docs/src/routes/docs/(qwikcity)/layout/index.mdx — adds a new "Named Slots in Layouts" section covering:
  • Why component$ pages can't target layout named slots (Virtual node boundary)
  • The inline component workaround with a complete layout + page example
  • How to layer component$ children inside the inline default export for pages that need hooks (useSignal, useStore, etc.)
  • The nested layouts constraint: intermediate layouts must also be inline components rendering {children} top-level inside a fragment (not wrapped in any HTML element), so q:slot attributes propagate all the way up to the outer layout's slot system
  • What breaks propagation (wrapping {children} in an HTML element stops flattening) and the component$ + <Slot /> alternative when a wrapper element is genuinely needed

Pattern

// layout.tsx — named slots defined normally
export default component$(() => (
  <div>
    <Slot name="breadcrumb" />
    <main><Slot /></main>
    <aside><Slot name="sidebar" /></aside>
  </div>
));

// products/layout.tsx — intermediate layout must be inline, {children} top-level in a fragment
export default ({ children }: any) => (
  <>
    <nav q:slot="breadcrumb"><a href="/">Home</a> / Products</nav>
    {children} {/* top-level — q:slot attributes inside are still visible to outer layout */}
  </>
);

// products/index.tsx — plain function default export; Qwik inlines its output
//                      so q:slot attributes reach the outer layout's slot system
export default () => (
  <>
    <aside q:slot="sidebar"><p>Category filters</p></aside>
    <div><h1>All Products</h1></div>   {/* → default <Slot /> */}
  </>
);

For reactive pages, wrap stateful parts in a component$ rendered inside the inline shell — hooks are unavailable in inline components directly.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5685fca

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[wmertens]

@copilot also document the constraint that if you have nested layouts, that intermediate layouts have to be inline components too, rendering {children} instead of <Slot />, and that those {children} have to be top-level (so inside a fragment).

[Copilot]

@copilot also document the constraint that if you have nested layouts, that intermediate layouts have to be inline components too, rendering {children} instead of <Slot />, and that those `{ch...

Added in 53e1ac6. The new "Nested layouts with named slots" subsection documents:

• Intermediate layouts must be inline components rendering {children} inside a fragment (not an HTML element)
• Explains why: _flatVirtualChildren recurses into inline functions but stops at HTML elements, so wrapping {children} in e.g. a <div> hides the inner q:slot attributes from the outer layout
• Shows ❌ broken pattern (div wrapper) and ✅ alternative (use component$ + <Slot /> if a wrapper element is genuinely needed)

[Copilot]

Pull request overview

Documents the Qwik City “inline component” technique required for pages (and intermediate layouts) to target named <Slot name="..."/> areas in parent layouts, explaining why component$ pages create an opaque boundary for slot projection.

Changes:

• Adds a new “Named Slots in Layouts” section explaining the component boundary issue and the inline-default-export workaround.
• Provides examples for: named-slot layouts, inline pages targeting named slots, nested layouts propagation rules, and a hook-friendly pattern (inline shell + component$ child).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@builder.io/qwik@8600

npm i https://pkg.pr.new/@builder.io/qwik-city@8600

npm i https://pkg.pr.new/eslint-plugin-qwik@8600

npm i https://pkg.pr.new/create-qwik@8600

commit: 5685fca

[github-actions]

built with Refined Cloudflare Pages Action

⚡ Cloudflare Pages Deployment

Name	Status	Preview	Last Commit
qwik-docs	✅ Ready (View Log)	Visit Preview	5685fca