> 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. 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.
The Colors sub-section in the Variables section in the Global tab.

In the Global tab and Variables section you'll find the list of color variables in your project.

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 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 Color variables 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.
The color field, hue slider, opacity slider and manual color input
#### 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 will be displayed 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 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.
Color variables shown in the color property of an element

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.

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 settings On the right side of the color variable row you can see the color and alpha value. Click any of them to make changes. {% endstep %} {% step %} ### Change the name and/or description To open up the full color variable edit window, click the pencil icon on the left side of the color variable row. Make the needed changes 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.
Finding uses of a specific color variable
{% stepper %} {% step %} ### Find the color variable Navigate to *Global*, *Variables* 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* will open and show 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
What's the difference between a color variable and picking a color directly? 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.
Can I use color variables in styles? 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.
What happens when I change a color variable? 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.
Can I delete a color variable that's still in use? You can, but any element referencing it will no longer be linked to it, and revert to a hardcoded color. Use [Find usages](#find-the-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 %}
How many color variables should I have? 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.
Can I use color variables in conditional properties? Yes. Conditional properties support color variables, so you can change an element's color based on a rule while still referencing your saved palette.
Can I organize color variables into groups? There's currently no way to organize color variables into groups or folders.
Do color variables work in both web and native mobile apps? Yes. Color variables are part of your app's design system and are available on both platforms.
Can I use color variables for dark mode? 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.

In this example, we have a field on the user called Dark mode, and if set to Yes, the style will use a different color. Note: this condition is placed on the style directly, not on an element.

[^1]: A hex code is a six-digit number used in to represent a specific color. It condenses RGB values into a single code.\ \ The first two digits of the hex code represent the red component, the middle two represent the green component, and the last two represent the blue component. [^2]: Alpha value in hex codes represents the opacity level of a color. While traditional hex color codes have 6 digits (e.g., #RRGGBB), adding an alpha value extends it to 8 digits (e.g., #RRGGBBAA). The two extra characters denote transparency, with '00' being fully transparent and 'FF' being fully opaque. These codes are generated automatically in Bubble.