What are Global Variables?#

Global Variables (GV) in Kustom are user-defined settings that can be applied across multiple modules or components simultaneously. They allow you to control various aspects of your design from a central location, making it easier to maintain consistency and implement theme-wide changes quickly.

How to use Globals#

If you open the Advanced Editor, you’ll notice a tab called “globals” on the first “root” container. This section allows you to add, remove, and modify Global variables.

Basic Usage Example#

Let’s say you have a preset with multiple text items and want to change the font of all these items from a single control point:

Create a Global of type “Font” in the Globals section
Go to a TextModule, select the “Font” preference
Click on the “Globe” icon in the action bar at the top
Select the Global you just created from the list
Repeat for all Text modules you want to control with that global

Now you can change the font of all connected modules by simply updating the Global preference in the main container.

Global Variable Types#

Kustom supports various types of Global Variables including:

Text
Number
Color
Toggle
List
Image
Font

Global persistency#

Starting with version 3.78 global Variables now have enhanced persistence capabilities:

Globals persist across device reboots
By default, when you change a global in the editor, the global on the preset will also be changed
This behavior can be modified in the app’s general settings if you prefer globals not to be automatically updated, in the settings you can decide weather the editor always overwrites the preset or never does

Using Globals in Formulas#

You can reference Global Variables in formulas using the $gv(name)$ syntax, where “name” is the name of your global, you can optionally provide a default as a second parameter that will be used when no value is set so $gv(name, default)$

Global History#

Kustom also keeps a small history of past values of each global. Every time the preset is saved the current value is stored, and you can read it back with the GH function: $gh(name, 0)$ is the current value, $gh(name, 1)$ the one before it, and a second argument of 1000 or more is treated as a unix timestamp so you can ask for the value at a moment in time.

How often the value is stored is controlled by the “Global persistence” option in Advanced Settings: “If changed” (the default) stores a value only when it differs from the last one, “Always” stores on every save, and “Never” disables history.

See the Read past values of a global with GH recipe for a full walkthrough with examples.

Best Practices#

Use descriptive names for your globals to easily identify their purpose
Create globals for elements that might change across themes (colors, fonts, sizes)
Consider using globals for information that needs to be updated frequently