# Override Shell Components

Copy complete examples for common Lotus component overrides.

Use these recipes after reviewing
[Overriding Components](/docs/customization/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.

```astro
---
---

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

### Reuse public

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

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

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

### Call slot

Use this when one override should respect another configured override.

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

```astro title="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>
```

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

```astro title="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>
```

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

```astro title="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.