# Overriding Components
Replace Dahlia shell components when configuration is not enough.
Use component overrides when a project needs to replace part of the Dahlia shell:
markup, placement, or behavior. Prefer normal theme configuration and CSS tokens
first. For example, use `pageActions`, `footer.sections`, 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 `dahlia({...})`. Paths are resolved from the project root.
```ts title="astro.config.ts"
import { defineConfig } from 'astro/config';
import dahlia from '@prosefly/astro-theme-dahlia';
export default defineConfig({
integrations: [
dahlia({
components: {
PageAside: './src/components/dahlia/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-dahlia/components`.
```txt
layout -> override slot -> default implementation -> public theme component
```
Use `dahlia({ 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](/docs/customization/theme-components/)
for the public export list.
## Override Points
Only these names are valid keys in the `components` object passed to
`dahlia({...})`.
| Name | Where It Renders | Props |
| --- | --- | --- |
| `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 |
| `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 below docs content. | `contributors`, `lastUpdated`, `title`, `currentLocale` |
| `PageNavigation` | Previous and next links below docs content. | `navigation`, `currentLocale?` |
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:
```astro title="src/components/dahlia/PageAside.astro"
---
import { PageAside } from '@prosefly/astro-theme-dahlia/components';
---
```
Register it:
```ts title="astro.config.ts"
dahlia({
components: {
PageAside: './src/components/dahlia/PageAside.astro',
},
})
```
Dahlia now renders this file anywhere the shell asks for `PageAside`.
## Reusing Existing Behavior
An override can still reuse Dahlia behavior. Import from
`@prosefly/astro-theme-dahlia/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.
```astro title="src/components/dahlia/PageHeader.astro"
---
import PageActions from 'virtual:prosefly/dahlia/components/PageActions';
---
```
## Translations
Dahlia 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.
## 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.