# Overriding Components Replace Lotus shell components when a project needs custom behavior. 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: ```ts 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: | Layer | Role | Public API | | --- | --- | --- | | `components/layout` | Internal page chrome such as header, footer, sidebars, and TOC. | No | | `components/defaults` | Default implementations for override slots. | No | | `components/theme` | Reusable theme components used by defaults and local overrides. | Yes | | `components/ui` | Low-level internal controls. | No | The shell renders override slots through virtual modules. A default slot usually delegates to a public theme component: ```txt 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`. | Name | Where It Renders | Props Passed By Lotus | | --- | --- | --- | | `Assistant` | Global assistant widget area near the end of ``. | none | | `SiteBrand` | Main header brand link. | none | | `HeaderNavbar` | Desktop header navbar and mobile menu navbar. | `currentPath?: string`, `mobile?: boolean` | | `HeaderSocialIcons` | Desktop header social area and mobile menu social area. | `mobile?: boolean` | | `FooterLinks` | Footer link grid. | none | | `SearchDialog` | Main header search trigger and dialog. | none | | `ThemeSwitch` | Desktop header and mobile menu theme mode area. | none | | `PageHeader` | Docs article title area. | `title`, `description?`, `sectionTitle?`, `pageActions`, `pageUrl`, `markdownUrl`, `currentLocale` | | `PageActions` | Action control inside `PageHeader`. | `actions`, `title`, `pageUrl`, `markdownUrl`, `currentLocale?` | | `PageAside` | Right sidebar content and mobile page tools. | `headings`, `editUrl`, `title`, `pageUrl`, `markdownUrl`, `currentSlug`, `currentLocale`, `tableOfContents?` | | `PageMeta` | Last updated and contributors between docs content and previous/next navigation. | `contributors`, `lastUpdated`, `title`, `currentLocale` | | `PageNavigation` | Previous and next links below docs content. | `navigation`, `currentLocale?` | 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: | Override Slot | Public Component To Reuse | | --- | --- | | `HeaderNavbar` | `NavbarLinks` | | `HeaderSocialIcons` | `SocialIcons` | | `FooterLinks` | `FooterLinks` | | `ThemeSwitch` | `ThemeModeButton`, `ThemeModeSegmentedControl`, `ThemeModeSelect`, or `ThemeModeSwitch` | | `SearchDialog` | `SearchDialog`, `SearchDialogTrigger`, `SearchDialogContent` | | `PageActions` | `PageActions` | | `PageAside` | `PageAside`, `EditThisPage` | | `PageHeader` | `PageHeader` | | `PageMeta` | `PageMeta`, `Contributors` | | `PageNavigation` | `PageNavigation` | | `SiteBrand` | `SiteBrand` | Use a public component import when you want the package implementation: ```astro --- import { PageActions } from '@prosefly/astro-theme-lotus/components'; --- ``` Use a virtual module only when one override needs to call another override slot and preserve the user's configured replacement: ```astro --- import PageActions from 'virtual:prosefly/lotus/components/PageActions'; --- ``` ## Minimal Override Create a local Astro component: ```astro title="src/components/lotus/SearchDialog.astro" --- --- Search ``` Register it: ```ts // src/theme.config.ts 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](/docs/configuration/i18n/#translator-api) for the translator API. ## Recipes For complete examples, see [Override Shell Components](/docs/recipes/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.