> ## Documentation Index
> Fetch the complete documentation index at: https://buttercms.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Component versioning

> Understand how versioning works for Components in ButterCMS, including schema changes and content revisions.

## Basics of ButterCMS versioning and history

<Tip>
  For a more in-depth overview of ButterCMS versioning and history functions, see [Revision history](../../versioning-history/revision-history-overview).
</Tip>

**Components** can be thought of as mini **schemas**; in the same way that a Page Type schema defines the **structure** of the fields for the entire Page instance, a Component defines the structure of the fields it contains.

ButterCMS provides versioning and history for the **content** of a Page instance or Collection item via its **history** feature, but the schemas themselves are not tracked. As such, there are limitations to be aware of when it comes to Global Components, particularly when it comes to restoring previous versions.

<Warning>
  Some changes made to a Global Component affect all versions of the Page in the Page's history. This is **necessary** so that we are able to restore previous versions of your content without also affecting all other Page content that uses the Component.
</Warning>

## Component changes and current versions

Imagine that your Component Library included a **Navigation** Global Component that was used on two Page Types, A and B, and you had created two Pages (or instances) of each of these Page Types.

If you made a change to this Component, such as **adding** a field, you would create four new drafts of Page content, i.e., one draft for each Page instance for each Page Type.

```mermaid theme={null}
flowchart TD
    NC["Global Component"]
    NC --> PTA["Page Type A"]
    NC --> PTB["Page Type B"]
    PTA --> A1["Page A-1"]
    PTA --> A2["Page A-2"]
    PTB --> B1["Page B-1"]
    PTB --> B2["Page B-2"]

    A1 & A2 & B1 & B2 --> D["4 new Page drafts created"]
```

## Component changes and versions in history

Imagine that you now want to revert Page Type A to a previous version. Because the Component is a Global Component, reversion would not only affect Page Type A, but also Page Type B, meaning it would likely be a ***breaking change*** for your content.

To avoid breaking linked content, **ButterCMS edits the previous versions of your content stored in history** when you make a change to an included Global Component.

Without these changes, it would be impossible to restore previous versions of your Page content, as the changes to Component structure would affect all other content that shares the Component.

```mermaid theme={null}
flowchart TD
    NC["Global Component"]
    NC --> PT1["Page Type A"]
    NC --> PT2["Page Type B"]
    PT1 --> P1["Page A-1"]
    PT1 --> P2["Page A-2"]
    PT2 --> P3["Page B-1"]
    PT2 --> P4["Page B-2"]

    subgraph add ["Field is ADDED"]
        direction LR
        A1["All previous history versions show new field with blank value"]
    end

    subgraph del ["Field is DELETED"]
        direction LR
        D1["All previous history versions no longer have that field"]
    end

    P1 & P2 & P3 & P4 --> add
    P1 & P2 & P3 & P4 --> del
```

<Warning>
  It is important to ***proceed carefully*** with changes to Components in your Component Library and make sure you will not need to restore content that includes these fields.
</Warning>

### Adding a field to a global Component

All previous versions of this Page in the history would now show this field in the Component, albeit with a blank value.

### Deleting a field from a global Component

If you **deleted** a field from the Global component, all previous versions of the Page in its History would no longer have that field on the Component.