Clarify how to override default components that use multiple slots. (#…

…2386) Co-authored-by: HiDeoo <[email protected]>
withastro · Nov 23, 2024 · ffac333 · ffac333
1 parent 3548fc3
commit ffac333
Show file tree

Hide file tree

Showing 2 changed files with 21 additions and 2 deletions.
diff --git a/docs/src/content/docs/guides/overriding-components.mdx b/docs/src/content/docs/guides/overriding-components.mdx
@@ -86,6 +86,23 @@ When rendering a built-in component inside a custom component:
 - Spread `Astro.props` into it. This makes sure that it receives all the data it needs to render.
 - Add a [`<slot />`](https://docs.astro.build/en/core-concepts/astro-components/#slots) inside the default component. This makes sure that if the component is passed any child elements, Astro knows where to render them.
 
+If you are reusing the [`PageFrame`](/reference/overrides/#pageframe) or [`TwoColumnContent`](/reference/overrides/#twocolumncontent) components which contain [named slots](https://docs.astro.build/en/basics/astro-components/#named-slots), you also need to [transfer](https://docs.astro.build/en/basics/astro-components/#transferring-slots) these slots as well.
+
+The example below shows a custom component that reuses the `TwoColumnContent` component which contains an additional `right-sidebar` named slot that needs to be transferred:
+
+```astro {9}
+---
+// src/components/CustomContent.astro
+import type { Props } from '@astrojs/starlight/props';
+import Default from '@astrojs/starlight/components/TwoColumnContent.astro';
+---
+
+<Default {...Astro.props}>
+	<slot />
+	<slot name="right-sidebar" slot="right-sidebar" />
+</Default>
+```
+
 ## Use page data
 
 When overriding a Starlight component, your custom implementation receives a standard `Astro.props` object containing all the data for the current page.

diff --git a/docs/src/content/docs/reference/overrides.md b/docs/src/content/docs/reference/overrides.md
@@ -195,7 +195,8 @@ When possible, prefer overriding a lower-level component.
 
 #### `PageFrame`
 
-**Default component:** [`PageFrame.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/PageFrame.astro)
+**Default component:** [`PageFrame.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/PageFrame.astro)  
+**Named slots:** `header`, `sidebar`
 
 Layout component wrapped around most of the page content.
 The default implementation sets up the header–sidebar–main layout and includes `header` and `sidebar` named slots along with a default slot for the main content.
@@ -209,7 +210,8 @@ Component rendered inside [`<PageFrame>`](#pageframe) that is responsible for to
 
 #### `TwoColumnContent`
 
-**Default component:** [`TwoColumnContent.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/TwoColumnContent.astro)
+**Default component:** [`TwoColumnContent.astro`](https://github.com/withastro/starlight/blob/main/packages/starlight/components/TwoColumnContent.astro)  
+**Named slot:** `right-sidebar`
 
 Layout component wrapped around the main content column and right sidebar (table of contents).
 The default implementation handles the switch between a single-column, small-viewport layout and a two-column, larger-viewport layout.