Custom Variables

Variables allow your widget to hold state that changes during user interaction. Use them to build pagination, tab navigation, date filters, and other interactive patterns -- all without a backend.

What are Variables?

Variables are key-value pairs defined in the widget editor under the Variables tab. Each variable has:

• Name -- a unique identifier (accessed in lowercase, e.g., my-var becomes {{variables.my-var}})
• Type -- determines how the value is stored and parsed
• Default value -- the initial value when the widget first renders

Variables are stored per widget instance and reset to their default values when the page reloads.

Variable Types

Type	Description	Default if empty
Text	A string value. Use for labels, filter keys, tab names, etc.	"" (empty string)
Number	A numeric value. Use for page indexes, counters, offsets, etc.	0
Date	An ISO date string. Works with the datetime Handlebars helper for formatting.	Current date/time

Using Variables in Templates

Reference any variable in your Handlebars template with the {{variables.<name>}} syntax. Variable names are always lowercase.

<p>Current page: {{variables.page}}</p>
<p>Selected filter: {{variables.filter}}</p>
<p>Today: {{datetime variables.selected-date "DD.MM.YYYY"}}</p>

tip

If your variable name contains special characters (like hyphens), use bracket notation: {{variables.[my-variable]}}

Using Variables in API Requests

You can use variables anywhere in your API request configuration -- URL, headers, or body:

https://api.example.com/items?page={{variables.page}}&filter={{variables.filter}}

When combined with the refetch parameter of setVariable(), changing a variable can automatically re-fetch data from the API with the updated value.

The setVariable() Function

setVariable() is a global JavaScript function that the Widget Builder injects into the page for each widget. Use it in onclick handlers to update variable values at runtime.

Syntax

setVariable(name, value, refetch)

Parameter	Type	Description
name	string	The variable name (case-insensitive).
value	string	The new value. Numbers and dates are passed as strings and parsed automatically based on the variable type.
refetch	boolean	Optional (default: false). When true, the widget re-fetches its API data and re-renders with the updated variable.

Example

<button onclick="setVariable('page', '2')">Go to page 2</button>
<button onclick="setVariable('page', '1', true)">Go to page 1 (and reload data)</button>

Interactive Patterns

Pagination

Use a number variable to track the current page and pass it to your API request.

Variables:

• page (Number, default: 0)

API URL:

https://api.example.com/items?offset={{variables.page}}&limit=10

Template:

{{#each data.items}}
  <div>{{this.title}}</div>
{{/each}}

<button onclick="setVariable('page', {{variables.page}} - 1, true)">Previous</button>
<button onclick="setVariable('page', {{variables.page}} + 1, true)">Next</button>

The true parameter triggers a data re-fetch with the new page value.

Date Navigation

Use a date variable to let users browse content by date -- for example, a meal plan or event schedule.

Variables:

• selected-date (Date, default: today)

Template:

<h3>Menu for {{datetime variables.[selected-date] "dddd, DD MMMM"}}</h3>

{{#each data.meals}}
  <div>{{this.name}} -- {{this.description}}</div>
{{/each}}

<button onclick="setVariable('selected-date', '{{dateAdd variables.[selected-date] -1 "days"}}', true)">
  Previous day
</button>
<button onclick="setVariable('selected-date', '{{dateAdd variables.[selected-date] 1 "days"}}', true)">
  Next day
</button>

Tabs / Filters

Use a text variable to switch between content categories without reloading.

Variables:

• tab (Text, default: all)

Template:

<div class="tabs">
  <button onclick="setVariable('tab', 'all')">All</button>
  <button onclick="setVariable('tab', 'news')">News</button>
  <button onclick="setVariable('tab', 'events')">Events</button>
</div>

{{#each data.items}}
  {{#if (or (eq ../variables.tab "all") (eq this.category ../variables.tab))}}
    <div>{{this.title}}</div>
  {{/if}}
{{/each}}

If the tab value is used in the API URL, add true as the third parameter to re-fetch data when switching tabs.

Best Practices

• Use descriptive names -- page, selected-date, active-tab are clearer than v1, d, t.
• Set sensible defaults -- A pagination variable should default to 0 or 1, a date variable to today's date.
• Use refetch only when needed -- Set the third parameter to true only when the API request depends on the variable. For purely client-side filtering or tab switching, omit it to avoid unnecessary API calls.
• Variable names are lowercased -- MyVar and myvar resolve to the same variable. Use lowercase names consistently to avoid confusion.