> For the complete documentation index, see [llms.txt](https://docs.civictheme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.civictheme.io/development/uikit/variables/overriding-components.md).

# Overriding components

This reference covers the process for overriding an existing CivicTheme component in your sub-theme — from deciding whether to override, through the copy-and-register process, to style-only alternatives.

## When to Override vs. Create New

| Situation                                                              | Approach                                                                                        |
| ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Change the look of an existing component (colors, spacing, layout)     | **Override** — modify the existing component in your sub-theme                                  |
| Change the behavior of an existing component (JavaScript interactions) | **Override** — modify the component's `.js` file                                                |
| Add a variant to an existing component (a new button style)            | **Override** — extend the component's template and SCSS                                         |
| Build something that does not map to any existing component            | **Create new** — see [Creating components](/development/uikit/variables/creating-components.md) |
| Combine existing components in a new way                               | **Create new** — compose a molecule or organism from existing atoms                             |

## Identifying the Component

Components are organised by atomic design level in the base CivicTheme theme:

```
civictheme/components/
├── 00-base/        # Foundation (variables, mixins, grid)
├── 01-atoms/       # Button, Tag, Heading, Link, etc.
├── 02-molecules/   # Cards, Accordion, Breadcrumb, etc.
├── 03-organisms/   # Header, Footer, Banner, Navigation, etc.
└── 04-templates/   # Page layouts
```

Use Storybook to browse components visually, or search the base theme's `components/` directory for the component name.

## Copy and Register

Copy the entire component directory from the base theme into the matching location in your sub-theme:

```bash
# Example: overriding the button component
cp -r path/to/civictheme/components/01-atoms/button \
      your_theme/components/01-atoms/button
```

Keep the same directory name and location within the atomic hierarchy. The build system matches components by directory name when merging.

In your copied `component.component.yml`, add a `replaces` key to declare the override:

```yaml
replaces: 'civictheme:button'
```

Both components must have compatible schemas — the props and slots in your override must match the original. You can add new props, but existing ones must remain compatible.

## Modifying the Component

Modify only the files you need to change — but for clarity and maintainability, it is recommended to copy the entire component directory.

CivicTheme components follow strict conventions for SCSS (BEM naming, design tokens, theme mixins), Twig (prop validation, class construction, nested includes with `only`), and JavaScript (constructor pattern, data-attribute selection, no jQuery). The complete file conventions and code patterns are documented in the [components system reference](/development/drupal-theme/systems/components.md).

## Style-Only Overrides (Simpler Alternative)

If you only need to change a component's visual appearance without modifying its template or JavaScript, you can override just the SCSS variables instead of copying the entire component.

Edit `components/variables.components.scss` in your sub-theme:

```scss
// Override button colors without copying the component
$ct-button-light-primary-background-color: #custom-color;
$ct-button-light-primary-hover-background-color: #custom-hover;
```

This is the lightest-touch approach and avoids maintaining a full copy of the component. Use it when variable overrides are sufficient. The variable override mechanism and naming conventions are documented in the [variables reference](/development/uikit/variables.md).

## Rebuild and Verify

After making changes:

```bash
npm run dist
npm run storybook
```

Check all variants of the component (light/dark theme, different sizes, states) in Storybook. Then clear Drupal caches (`drush cr`) and verify on the live site.

## Common Pitfalls

For common issues (forgetting to rebuild, namespace conflicts, breaking the prop schema, preprocess hook dependencies), see the [common pitfalls](/development/drupal-theme/systems/components.md#common-pitfalls) section of the components system reference.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.civictheme.io/development/uikit/variables/overriding-components.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.