Overriding Components

Component overrides replace specific pieces of the Lotus documentation shell. Use them when configuration and CSS tokens are not enough because the rendered markup, placement, or behavior needs to change.

Overrides are configured in src/theme.config.ts through the components object:

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

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

Paths are resolved from the project root. They can be relative paths like ./src/components/lotus/SearchDialog.astro or absolute file-system paths.

How Overrides Work

Lotus separates shell structure from reusable components:

The shell renders override slots through virtual modules. A default slot usually delegates to a public theme component:

layout -> virtual override slot -> defaults -> theme

For example, the main header renders the HeaderNavbar slot. The default HeaderNavbar implementation delegates to the public NavbarLinks component.

When To Override

Start with normal theme configuration for content, labels, links, actions, sidebars, footer sections, color mode, accent color, gray scale, and radius. Use CSS tokens for fonts and visual tuning.

Use a component override when the project needs to:

• Replace the search UI with another search provider.
• Change the header brand markup.
• Move, hide, or restyle page actions beyond what pageActions supports.
• Replace the page contributors block.
• Replace previous and next page navigation.
• Use a different theme mode control.
• Change the navbar or social-link rendering while keeping the same config data.
• Change footer link rendering while keeping footer.sections as the source data.

Override Points

Override point names are slot names, not always public component export names. Use these names in themeConfig.components.

Only these names are supported by the components config. Other components can still be imported from @prosefly/astro-theme-lotus/components, but importing a component does not make it an override point.

Slot And Export Names

Common slot and export pairs:

Use a public component import when you want the package implementation:

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

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

Use a 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} />

Minimal Override

Create a local Astro component:

---
---

<a
  class="lotus-focus-ring rounded-(--lotus-radius-md) px-3 py-2 text-sm text-(--lotus-text-muted)"
  href="/search/"
>
  Search
</a>

Register it:

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

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

Lotus now renders this file anywhere the shell asks for SearchDialog.

Props And Translations

Astro.props contains the props Lotus passes to that override point. Forward those props when reusing a public theme component so built-in behavior keeps working.

Lotus also provides the resolved UI translator on Astro.locals.t. Use it when visible shell text should follow the current locale. See Internationalization for the translator API.

Recipes

For complete examples, see Override Shell Components.

Debugging

If an override does not appear:

• Confirm the key matches one of the supported override point names exactly.
• Confirm the file path is relative to the project root.
• Restart the dev server after changing src/theme.config.ts.
• Check that the override file has a default Astro component export, which is what .astro files provide by default.
• Forward Astro.props when reusing a public theme component.