Overriding Components

Use component overrides when a project needs to replace part of the Lotus shell: markup, placement, or behavior. Prefer normal theme configuration and CSS tokens first. For example, use pageActions, footer.sections, themeModeControl, accent colors, gray scale, radius, and CSS variables before replacing a component.

Overrides are configured in astro.config.ts through the components object passed to lotus({...}). Paths are resolved from the project root.

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

export default defineConfig({
  integrations: [
    lotus({
      components: {
        PageAside: './src/components/lotus/PageAside.astro',
      },
    }),
  ],
});

How It Works

The shell renders named override slots. Each slot has a default implementation, and many defaults delegate to public theme components exported from @prosefly/astro-theme-lotus/components.

layout -> override slot -> default implementation -> public theme component

Use lotus({ components }) with override slot names such as PageAside or PageActions. Import public theme components only when your local override wants to reuse package behavior. See Theme Components for the public export list.

Override Points

Only these names are valid keys in the components object passed to lotus({...}).

Importing a public component does not make it an override point. The configured key must be one of the slot names above.

Minimal Override

Create a local Astro component for the slot. This example keeps the default right sidebar and adds an EthicalAds placement below it:

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

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

<aside class="mt-6 border-t border-(--lotus-border-subtle) pt-5">
  <script
    async
    src="https://media.ethicalads.io/media/client/ethicalads.min.js"
  ></script>
  <div
    class="flat"
    data-ea-publisher="your-publisher-id"
    data-ea-type="text"
  ></div>
</aside>

Register it:

lotus({
  components: {
    PageAside: './src/components/lotus/PageAside.astro',
  },
})

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

Reusing Existing Behavior

An override can still reuse Lotus behavior. Import from @prosefly/astro-theme-lotus/components when you want the package implementation, and forward Astro.props if the component receives props.

Use a virtual module when one override needs to call another configured override slot. This preserves the user’s replacement instead of forcing the package implementation.

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

<header>
  <h1>{Astro.props.title}</h1>
  <PageActions
    actions={Astro.props.pageActions}
    currentLocale={Astro.props.currentLocale}
    markdownUrl={Astro.props.markdownUrl}
    pageUrl={Astro.props.pageUrl}
    title={Astro.props.title}
  />
</header>

Translations

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

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 astro.config.ts.
• Check that the override file has a default Astro component export.
• Forward Astro.props when reusing a public theme component.