# Theme Components

Reuse public Lotus theme components inside local overrides.

import { CodeBlock } from '@prosefly/astro-theme-lotus/components';

Lotus exports composable theme components from
`@prosefly/astro-theme-lotus/components`. Use them when an override should wrap
or rearrange the default behavior instead of replacing it from scratch.

These exports come from Lotus' `components/theme` layer. They are reusable
building blocks, not the internal page chrome. Lotus does not export
`components/layout`, `components/defaults`, or `components/ui`.

For custom Astro pages that need a full page shell, use
`@prosefly/astro-theme-lotus/layouts` instead. See [Page Layouts](/docs/customization/page-layouts/).

An override slot and a public component can have different names. For example,
the shell slot is `HeaderNavbar`, while the reusable public component is
`NavbarLinks`.

## Public Exports

| Export | Purpose |
| --- | --- |
| `AppearancePalette` | Complete appearance palette control. |
| `AppearancePaletteContent` | Palette popover content without the trigger wrapper. |
| `Assistant` | Hosted assistant widget loader. |
| `AssistantTrigger` | Ask AI trigger button shown near search. |
| `CodeBlock` | Static Shiki-highlighted code block for custom pages. |
| `Contributors` | Contributors block below docs content. |
| `Credits` | Built with Lotus footer credit. |
| `EditThisPage` | Edit link used by the page aside. |
| `FooterLinks` | Footer link sections rendered from `footer.sections`. |
| `LanguageSelect` | Locale selector for configured locales. |
| `LotusMark` | Built-in Lotus logo mark. |
| `NavbarLinks` | Header navbar links and action buttons. |
| `PageActions` | Copy, Markdown, and assistant page actions. |
| `PageAside` | Right sidebar content with table of contents and edit link. |
| `PageHeader` | Page title area with description and actions. |
| `PageMeta` | Last updated and contributors area below docs content. |
| `PageNavigation` | Previous and next page links. |
| `SearchDialog` | Complete search trigger and dialog. |
| `SearchDialogContent` | Search dialog body and client behavior. |
| `SearchDialogTrigger` | Search trigger buttons. |
| `SiteBrand` | Brand logo link. |
| `SocialIcons` | Social icon list. |
| `ThemeModeButton` | Icon button for cycling or selecting theme mode. |
| `ThemeModeSegmentedControl` | Segmented light, dark, and system control. |
| `ThemeModeSelect` | Select control for theme mode. |
| `ThemeModeSwitch` | Default header theme control. |

These exports are package-level building blocks. The theme shell imports
override points through internal virtual modules, so importing public components
inside an override does not recursively import the override file.

Use the public export when you want the package implementation:

```astro
---
import { NavbarLinks } from '@prosefly/astro-theme-lotus/components';
---

<NavbarLinks {...Astro.props} />
```

Use the virtual module only when one override needs to call another override
slot and preserve the user's configured replacement:

```astro
---
import PageActions from 'virtual:prosefly/lotus/components/PageActions';
---

<PageActions {...Astro.props} />
```

## Wrapping Search

```astro
---
import { SearchDialog } from '@prosefly/astro-theme-lotus/components';
---

<div class="rounded-(--lotus-radius-md) border border-(--lotus-border-muted) p-1">
  <SearchDialog />
</div>
```

Use the smaller search components when the trigger and dialog content need to
live in different places:

```astro
---
import {
  SearchDialogContent,
  SearchDialogTrigger,
} from '@prosefly/astro-theme-lotus/components';
---

<SearchDialogTrigger />
<SearchDialogContent />
```

## Wrapping Page Actions

```astro
---
import { PageActions } from '@prosefly/astro-theme-lotus/components';
---

<div class="rounded-(--lotus-radius-md) bg-(--lotus-surface) p-1">
  <PageActions {...Astro.props} />
</div>
```

Use this pattern when a project wants a different container or placement while
keeping the default copy, Markdown, ChatGPT, and Claude behavior.

## Highlighting Code

Use `CodeBlock` on custom Astro pages that are not rendered from Markdown.
Markdown fenced code blocks still use the configured Markdown and Expressive
Code pipeline.

<CodeBlock
  lang="ts"
  title="astro.config.mjs"
  code={`import lotus from '@prosefly/astro-theme-lotus';

export default {
  integrations: [lotus()],
};`}
/>

```astro
---
import { CodeBlock } from '@prosefly/astro-theme-lotus/components';
---

<CodeBlock
  lang="ts"
  title="astro.config.mjs"
  code={`import lotus from '@prosefly/astro-theme-lotus';

export default {
  integrations: [lotus()],
};`}
/>
```

## Reusing Theme Mode Controls

```astro
---
import {
  ThemeModeButton,
  ThemeModeSegmentedControl,
  ThemeModeSelect,
  ThemeModeSwitch,
} from '@prosefly/astro-theme-lotus/components';
---

<ThemeModeSwitch />
```

All theme mode controls use the same `lotus-theme` local storage key and update
the document `data-theme` attribute.

## Pair With Overrides

Use the `components` configuration to replace shell-owned slots:

```ts
export default defineLotusConfig({
  components: {
    PageActions: './src/components/lotus/PageActions.astro',
    SearchDialog: './src/components/lotus/SearchDialog.astro',
  },
});
```

Slot names are configured with names like `HeaderNavbar` and
`HeaderSocialIcons`. Public imports use names like `NavbarLinks` and
`SocialIcons`.

See [Overriding Components](/docs/customization/overriding-components/) for the
complete override list and path resolution rules.