Lotus
Type to search documentation.

Override Shell Components

Copy complete examples for common Lotus component overrides.

View as MarkdownOpen in ChatGPTOpen in Claude

Use these recipes after reviewing Overriding Components. Each example replaces one shell slot through themeConfig.components.

Override Patterns

Replace

Use this when the default slot behavior is not useful for the project.

---
---


<a href="/search/">Search</a>

Reuse public

Use this when the package default behavior is correct and only the wrapper or placement changes.

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


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

Call slot

Use this when one override should respect another configured override.

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


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

Reuse Page Actions

This override keeps the default copy, Markdown, ChatGPT, Claude, and custom actions, but changes the surrounding container.

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


<div class="rounded-(--lotus-radius-md) bg-(--lotus-surface) p-1">
  <PageActions {...Astro.props} />
</div>
export default defineLotusConfig({
  components: {
    PageActions: './src/components/lotus/PageActions.astro',
  },
});

Custom Header Social Area

This override keeps the configured social icons, replaces the default theme control, and still works in both desktop and mobile header contexts.

src/components/lotus/HeaderSocialIcons.astro
---
import {
  SocialIcons,
  ThemeModeButton,
} from '@prosefly/astro-theme-lotus/components';


interface Props {
  mobile?: boolean;
}


const { mobile = false } = Astro.props;
---


<div class:list={[
  'flex items-center',
  mobile ? 'gap-1' : 'gap-2',
]}>
  <SocialIcons mobile={mobile} />
  <ThemeModeButton />
</div>
export default defineLotusConfig({
  components: {
    HeaderSocialIcons: './src/components/lotus/HeaderSocialIcons.astro',
  },
});

HeaderSocialIcons receives mobile because Lotus uses the same override in the desktop header and mobile menu.

Custom Page Header

This override changes the page title layout while keeping the configured PageActions override point inside it.

src/components/lotus/PageHeader.astro
---
import PageActions from 'virtual:prosefly/lotus/components/PageActions';
import type { NormalizedLocale } from '@prosefly/astro-theme-lotus';
import type { PageActionConfig } from '@prosefly/astro-theme-lotus';


interface Props {
  title: string;
  description?: string;
  sectionTitle?: string;
  pageActions?: PageActionConfig[];
  pageUrl: string;
  markdownUrl: string;
  currentLocale?: NormalizedLocale;
}


const {
  title,
  description,
  sectionTitle,
  pageActions = [],
  pageUrl,
  markdownUrl,
  currentLocale,
} = Astro.props;
---


<header class="lotus-border-subtle border-b pb-8">
  {sectionTitle && (
    <p class="text-sm font-medium text-(--lotus-accent)">{sectionTitle}</p>
  )}
  <div class="mt-3 flex flex-col gap-4 sm:flex-row sm:items-end sm:justify-between">
    <div class="min-w-0">
      <h1 class="text-4xl font-semibold text-(--lotus-text-strong)">
        {title}
      </h1>
      {description && (
        <p class="mt-3 max-w-2xl text-base leading-7 text-(--lotus-text-muted)">
          {description}
        </p>
      )}
    </div>
    {pageActions.length > 0 && (
      <PageActions
        actions={pageActions}
        currentLocale={currentLocale}
        markdownUrl={markdownUrl}
        pageUrl={pageUrl}
        title={title}
      />
    )}
  </div>
</header>

Use virtual:prosefly/lotus/components/PageActions inside a shell override when the override should respect another local PageActions override. Use the public @prosefly/astro-theme-lotus/components export when you specifically want the package theme component and do not want to recurse through the override slot.

Last updated Jul 18, 2026

Contributors