> 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/playbook/govcms/04-overriding-components.md).

# Overriding Existing Components

This chapter covers the most common development task on a CivicTheme project: changing how an existing component looks or behaves. Rather than modifying the base theme (which must never be changed), you copy component files into your sub-theme and modify them there. The build system automatically picks up your version and uses it instead of the original.

## Prerequisites

* [ ] Sub-theme set up with build system working (see [Chapter 2](/playbook/govcms/02-sub-theme-setup.md))
* [ ] Storybook running locally for preview
* [ ] Familiarity with Twig, SCSS, and BEM naming conventions

## Overview

Before overriding a component, decide whether you actually need an override or a new component. Then follow the copy-and-register process: copy the component directory, add a `replaces` key, and modify only what's needed. For style-only changes, you can override SCSS variables without copying the component at all.

The full override process — when to override vs. create new, the copy-and-register steps, style-only alternatives, and rebuild/verify workflow — is documented in the [overriding components reference](/development/uikit/variables/overriding-components.md).

The file conventions (Twig, SCSS, JS patterns) and common pitfalls are in the [components system reference](/development/drupal-theme/systems/components.md).

## Next step

When overriding an existing component is not enough and you need something entirely new, the next chapter covers creating components from scratch.

Continue to [Chapter 5: Creating New Components](/playbook/govcms/05-creating-components.md).


---

# 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/playbook/govcms/04-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.