> For the complete documentation index, see [llms.txt](https://manual.bubble.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://manual.bubble.io/help-guides/design/variables-and-styles/color-variables.md).

# Color variables

Color variables are named colors you save once and reuse across your app. Learn how to create, name, apply, and update them, and how to find where each one is used.

Color variables are named colors you save once and reuse across your app. Instead of picking the same [hex code](#user-content-fn-1)[^1] and [alpha value](#user-content-fn-2)[^2] every time you style an element, you reference the variable, keeping your color choices consistent everywhere they're used.

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FxXIdge9Lx7RxZoRfkvUe%2Fcolor-variables.png?alt=media&amp;token=5cbc61b9-763e-4ead-8b48-d39dd101490b" alt="The Colors list in the Variables section, showing color variables such as Primary, Text, Surface, and Success with their hex codes and opacity."><figcaption><p>The <em>Variables</em> section of the <strong>Global</strong> tab lists the color variables in your project.</p></figcaption></figure>

When you update a color variable, every element that uses it updates too. This makes it much easier to iterate on your app's look and feel, especially as your app grows.

## What color variables are for

Most apps rely on a small palette of colors that appear over and over: brand colors, background colors, text colors, and status colors like success and error. Without variables, each of those colors ends up scattered across your app, hardcoded on individual elements or in styles. Updating one color means finding and updating every style and element that uses it.

Color variables replace that pattern with a single, named reference. Once a color is saved as a variable, it becomes part of your design system, available to any element or style that needs it.

## Creating a color variable

To create a color variable:

{% stepper %}
{% step %}

#### Navigate to the variables section

Open the **Global** tab and click the *Variables* section.
{% endstep %}

{% step %}

#### Find the color variables

Scroll down until you see the *Colors* header.
{% endstep %}

{% step %}

#### Create a new variable

Click the *New color variable* button in the upper-right corner of the *Colors* section.
{% endstep %}

{% step %}

#### Name the new variable

The name is how you'll reference the color in the editor, so it should make the variable easy to identify at a glance.

* **Name by role, not appearance.** *Primary* is more useful than *Blue*, because the name still makes sense if you change the color later. Naming by appearance breaks down as soon as your palette evolves.
* **Group related variables with a prefix.** Prefixes like *Text*, *Background*, and *Border* help related colors sort together and make the picker easier to scan. For example: *Text default*, *Text muted*, *Text inverse*.
* **Be specific but concise.** *Background subtle* is clearer than *Background* if you have more than one background variable. Aim for names that describe purpose in as few words as possible.
* **Match your team's naming conventions.** If you're working with others, agree on a naming pattern early. Consistency across the palette is more valuable than any specific naming choice.
  {% endstep %}

{% step %}

#### Describe the color variable

Descriptions aren't required, but they're useful for anyone (including future you) trying to understand what the variable is meant for.

* **Explain the intent, not the color.** A description like *Used for primary calls to action* is more helpful than *Bright blue used on buttons*. The intent is what stays consistent even if the color changes.
* **Note where it should be used.** If a variable has a specific purpose, spell it out. For example: *Backgrounds behind cards and modals* or *Error states, including borders and text*.
* **Note where it shouldn't be used.** If two variables are similar, describing when to pick one over the other prevents mix-ups. For example: *Use for headings only; body text should use Text default*.
* **Keep it short.** A sentence or two is usually enough. Descriptions are meant to give quick clarity, not full documentation.
  {% endstep %}

{% step %}

#### Pick a color

The color picker gives you a few different ways to choose the color for your variable. Any of the methods below can be used together to fine-tune the exact shade you want.

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FCqawWm0rU7JPKidsSeR1%2Fcolor-picker.png?alt=media&amp;token=50362370-15df-46a9-b556-9b69e1eb6fca" alt="The color picker, with the color field, hue slider, opacity slider, and hex code input set to #000000 at 100%."><figcaption><p>The color picker: the color field at the top, the hue and opacity sliders below it, and the hex code and opacity input at the bottom.</p></figcaption></figure>

#### The color field

The large square is where you pick the color's saturation and brightness. Click anywhere inside it to select a color, or drag the marker to adjust. Moving up brightens the color, moving down darkens it. Moving right adds saturation, moving left removes it.

#### The hue slider

The narrow band below the color field is the hue slider. It runs across the color spectrum, from red on the left through green, blue, and back to red. Slide the marker along the band to change the base hue, then use the color field above to adjust the saturation and brightness.

#### The opacity slider

The checkered slider below the hue slider controls opacity. Slide left to make the color more transparent, or right to make it fully opaque. Opacity is useful for overlays, subtle backgrounds, and softer highlights.

#### The hex code and opacity input

At the bottom, you can type a hex code directly. This is the fastest way to enter an exact color, especially when working from a brand palette or design system. The percentage next to the hex code shows the current opacity.

You can also copy hex codes out of the field to reuse the same color elsewhere, or paste in codes you've picked from another tool.
{% endstep %}

{% step %}

#### Save it

Click *Create* to save the new color variable. It appears in the list of color variables and can be used right away.
{% endstep %}
{% endstepper %}

## Using color variables

Anywhere you'd normally set a color in the element property editor, you can pick a color variable instead. The color picker shows your saved variables alongside the standard color options, making it easy to apply the right one.

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2Fku6WOCtol8SPRbhGtHn5%2Fcolor-variables.png?alt=media&amp;token=c985e056-cbf4-4a50-9be4-507cda58401e" alt="The Edit color popup with the color picker at the top and a highlighted Variables panel of color swatches below it."><figcaption><p>Color variables are available anywhere you work with colors. In this example, we're setting the background color of an element. The top section lets you pick a custom color, while the highlighted bottom section lets you pick from your saved color variables.</p></figcaption></figure>

Color variables can be used in:

* **Element properties**, such as backgrounds, borders, text color, and shadows.
* **Styles**, so an entire component's color palette is built from your variables.
* **Conditional properties**, letting you change an element's color based on a rule while still using variables.

## Updating a color variable

{% stepper %}
{% step %}

#### Navigate to the variables section

Open the **Global** tab and click the *Variables* section.
{% endstep %}

{% step %}

#### Find the color variable

Scroll down until you see the *Colors* header, and then find the color variable you want to update.
{% endstep %}

{% step %}

#### Set the new color and alpha value

On the right side of the color variable row, you can see the color and alpha value. Click either of them to make changes.
{% endstep %}

{% step %}

#### Change the name or description

To open the full color variable edit window, click the pencil icon on the left side of the color variable row. Make the changes you need and click *Save*.
{% endstep %}

{% step %}

#### The color is updated everywhere

The color is now updated everywhere it's used in your project.
{% endstep %}
{% endstepper %}

This is what makes color variables so powerful. Instead of tracking down every place a color is used, you can change your app's palette in one place and see the change propagate everywhere.

## Searching for components using a specific color variable

*Find usages* is useful when you want to review the impact of a change before making it, clean up unused variables, or trace inconsistencies in your design. It's especially helpful in larger apps, where the same variable can be referenced in many places across pages, reusable elements, and workflows.

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FN9RljCsYWiaecN9uBsv4%2Fsearch-color-variable-usage.png?alt=media&amp;token=65d1f287-ff66-4ee5-a692-eb9e97aa6c9c" alt="A list of color variables with the ... menu open on one row, showing the Find usages and Delete options."><figcaption><p>Open the <em>...</em> menu on a color variable's row and click <em>Find usages</em> to see where it's used.</p></figcaption></figure>

{% stepper %}
{% step %}

#### Find the color variable

Go to the **Global** tab and the *Variables* section, and scroll to the color variable you want to search for.
{% endstep %}

{% step %}

#### Open the contextual menu

Click the ... menu on the right side of the color variable row and click *Find usages*.
{% endstep %}

{% step %}

#### Click the component in the search results

The *App search tool* opens and shows all components that use the color variable. Click one to focus on it in the editor.
{% endstep %}
{% endstepper %}

## Common uses of color variables

Color variables work best when they reflect the roles colors play in your design, rather than the specific colors themselves. A good starting palette often includes:

* **Brand colors**, such as *Primary* and *Secondary*.
* **Background colors**, such as *Background default* and *Background subtle*.
* **Text colors**, such as *Text default*, *Text muted*, and *Text inverse*.
* **Border colors**, such as *Border default* and *Border strong*.
* **Status colors**, such as *Success*, *Warning*, *Error*, and *Info*.

Building your palette this way makes it easier to maintain, easier to explain to collaborators, and easier to adjust as your design evolves.

## Tips for working with color variables

* **Name variables by role, not appearance.** *Primary* is easier to work with than *Blue*, because it stays accurate even if the color changes.
* **Keep the palette small.** A tight palette is easier to reason about and enforces consistency. Aim for a handful of well-chosen variables rather than a large list.
* **Use variables in styles.** Applying color variables inside your styles is what ties the whole system together. Elements pick up colors indirectly through the styles they use.
* **Plan for dark mode from the start.** If you know your app will support dark mode, name your variables in a way that makes both light and dark values easy to define, such as *Background default* rather than *White*.

## FAQ: Color variables

<details>

<summary>What's the difference between a color variable and picking a color directly?</summary>

A color variable is a saved, named color that can be reused across your app. Picking a color directly hardcodes the specific hex code into that element, so it can't be updated centrally.

Color variables make it easy to keep your palette consistent and to change colors in one place.

</details>

<details>

<summary>Can I use color variables in styles?</summary>

Yes. Styles can reference color variables just like individual elements can. Using variables inside styles is what ties the whole design system together, since your elements pick up colors indirectly through the styles they use.

</details>

<details>

<summary>What happens when I change a color variable?</summary>

Every element and style that uses the variable updates automatically to reflect the new color. This is one of the main reasons to use color variables in the first place.

</details>

<details>

<summary>Can I delete a color variable that's still in use?</summary>

You can, but any element referencing it will no longer be linked to it and will revert to a hardcoded color. Use [Find usages](#searching-for-components-using-a-specific-color-variable) to review where the variable is used before deleting it, so you can update or replace it where needed.

{% hint style="warning" %}
Deleting a color variable can't be undone, so proceed with care.
{% endhint %}

</details>

<details>

<summary>How many color variables should I have?</summary>

There's no strict rule, but a small, well-chosen palette is easier to maintain than a large one. Most apps do well with a set that covers brand colors, backgrounds, text, borders, and a few status colors.

</details>

<details>

<summary>Can I use color variables in conditional properties?</summary>

Yes. Conditional properties support color variables, so you can change an element's color based on a rule while still referencing your saved palette.

</details>

<details>

<summary>Can I organize color variables into groups?</summary>

There's currently no way to organize color variables into groups or folders.

</details>

<details>

<summary>Do color variables work in both web and native mobile apps?</summary>

Yes. Color variables are part of your app's design system and are available on both platforms.

</details>

<details>

<summary>Can I use color variables for dark mode?</summary>

Yes. One common approach is to set up a conditional on a style that checks a value on the user, such as a *dark mode* toggle, and changes the color accordingly.

<figure><img src="https://34394582-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M5sbzwG7CljeZdkntrL%2Fuploads%2FGAlgyXfYO3MpsvOHBsoT%2Fdark-mode-conditional.png?alt=media&amp;token=fe1cf888-9bac-4413-89d2-dce582d4d103" alt="A conditional that sets the Background property to the Dark mode color variable when Current User&#x27;s Dark mode is yes."><figcaption><p>In this example, we have a field on the user called <em>Dark mode</em>, and if set to <em>Yes</em>, the style will use a different color. <strong>Note:</strong> This condition is placed on the style directly, not on an element.</p></figcaption></figure>

</details>

[^1]: A hex code is a six-character code used to represent a specific color. It condenses RGB values into a single code.\
    \
    The first two characters of the hex code represent the red component, the middle two represent the green component, and the last two represent the blue component.

[^2]: The alpha value in a hex code represents the opacity level of a color. While traditional hex color codes have six characters (for example, #RRGGBB), adding an alpha value extends them to eight characters (for example, #RRGGBBAA).\
    \
    The two extra characters set the transparency, with 00 being fully transparent and FF being fully opaque.\
    \
    These codes are generated automatically in Bubble.
