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

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

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:

---
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:

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

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

Wrapping Search

---
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:

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

<SearchDialogTrigger />
<SearchDialogContent />

Wrapping Page Actions

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

import lotus from '@prosefly/astro-theme-lotus';

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

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

---
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:

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 for the complete override list and path resolution rules.