> 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.civictheme.io/playbook/govcms/04-overriding-components.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.