What are Webflow Variables?

Webflow Variables are dynamic design parameters that allow for specific value assignments to human-readable terms. Think of them as the "settings'' that dictate design elements like colors and typography, ensuring that designs are adaptable, consistent, and easily modifiable.

For Webflow users, Variables are the key to maintaining design consistency across different parts of a website. Designers love them because they simplify the process of making site-wide design changes. Instead of manually adjusting each element, a single tweak to a Variable can cascade changes throughout the site. Marketers and other Stakeholders appreciate the ease and flexibility Variables bring, ensuring that branding and design elements remain cohesive and true to the brand's vision.

What Can I Build?

The Variables API offers you the chance to supercharge the way Webflow users interact with design parameters. Imagine crafting advanced functionalities that allow for more granular control over design elements, or integrating Variables with other systems to create a more interconnected and dynamic design experience. The potential is vast, and the combination of the Components and Variables API is your toolkit to unlock it.

This documentation provides an overview of how to create Variables and seamlessly integrate them into styles. If you’re looking to learn more about Variables, Webflow University offers a comprehensive overview of when and how to use them to improve the design process, allowing for swift, large-scale modifications.

Working with Collections

Collections are an organizing layer for Variables. Once you've selected your collection, you can access your variables.

Select the Default Collection

All variables are scoped to a Variable Collection. Currently, we only allow creation of variables and fetching of variables from the default collection through the Webflow object.

const collection = webflow.getDefaultVariableCollection()
// This collection object can now be used to create variables or access variables within it

const variable = collection.getVariableByName('Space Cadet')

Working with Variables

Creating a Variable

Webflow offers the capability to create three types of variables: color, length, and font-family. Each variable type can be created using a specific function. The variable names must be unique across the collection.

General Syntax

collection.createXXXVariable(variable-name, variable-value);

Selecting a Variable

Variables can be selected from their Collection by their name or ID.

const collection = webflow.getDefaultVariableCollection()
const variableById = collection.getVariable('id-123')
const variableByName = collection.getVariableByName('Space Cadet')

Editing a Variable

Renaming and setting new values on a Variable.

Renaming a Variable
Variables in Webflow can be renamed for better clarity or organization. It's important to ensure that the new name isn't already in use, as the renaming process will fail. After you've successfully renamed a variable, all instances where this variable is used will automatically reference the new name.

const variable = collection.getVariableByName("Space Cadet")
variable.setName('Our awesome bg color')

Setting a Variable value
While the type of a variable in Webflow remains fixed and cannot be changed, its value can be updated. The format for updating the value is consistent with its initial declaration.

const variable = collection.getVariable('id-123')
variable.set("#fffcc11");

Applying Variables to Styles

After defining your variables, you can incorporate them into your styles. To do this, simply use the variable as the property value in the style you're customizing.

const style = await webflow.getStyleByName(styleName)
const variable = collection.getVariable("id-123")

if (style) {
	style.setProperties({ "font-size": variable })
}

Applying a Variable as an Alias
In Webflow, you can use a variable as a reference when defining another variable. This means the value of the second variable will be determined by the value of the first variable they both refer to. It's essential that both variables are of the same type for this to work.

In the below example, both the variables are of type ColorVariable.

const firstVariable = collection.createColorVariable(
'Default Color', 'red'
)

const secondVariable = collection.createColorVariable(
'Space Cadet', firstVariable
)

Removing a variable

Deleting a Variable
Variables in Webflow can also be deleted. When a variable is removed, it undergoes a "soft delete" process, similar to the approach taken in the Webflow user interface. Notably, the remove() function for variables is immediate and doesn't necessitate the use of the save() method, setting it apart from the Elements APIs.

const variable = collection.getVariable('id-123')
variable.remove()

Variable Methods

Get Name

getName(): Promise<string | null>

Description: Get a list of all variables associated with a collection.
Returns: A Promise that resolves into a the Variable Name

Example

const collection = await webflow.getDefaultVariableCollection();  
const variable = collection.getVariable('id-123')
const variableName = variable.getName()

Set Name

setName(name: string): Promise<void>

Description: Set variable name.
Parameters:

• Name: string - The desired name of the variable.

Returns: A Promise that resolves once a name is successfully set

Example

const collection = await webflow.getDefaultVariableCollection();
const colorVariable = await collection.getVariableByName("color");
await colorVariable.setName("White");

Get Value

get(): Promise<ColorValue | LengthValue | FontFamilyValue | Variable | null>

Description: Get the variable’s value.
Returns: A Promise that resolves into a value, or if the variable is an alias - the original Variable.

const newVariable1 = await collection.createSizeVariable('myvar1', { unit: 'px', value: 50 });
console.log(await newVariable1.get());

Set Value

set: (value : string | LengthValue | Variable) : Promise<Void>

Description: Set value of variable. The value must be of the same type as the value of the instantiated variable.
Parameters:

• Value: ColorValue | LengthValue | FontFamilyValue | Variable

Returns: A Promise that resolves into a value, or if the variable is an alias - the original Variable.

Example

const newVariable1 = await collection.createColorVariable('myvar4', 'red');
await newVariable1.set('yellow');

Remove Variable

remove(): Promise<boolean>

Description: Removes a variable from the default collection
Returns: A Promise that resolves into a boolean indicating whether deleting the variable was successful or not.

 const newVariable1 = await collection.createColorVariable('myvar4', 'red')
 newVariable1.remove()