Variables in Ditto allow teams to integrate dynamic values into their text.
From names to counts to links, variables make it easy for teams to integrate dynamic values, without requiring engineers to manually restructure content and without interfering with the display of text in designs. 🙌
👉Quick note: Variables are only available for linkable groups of text in Ditto, not draft groups of text. For more information on the difference between linkable and draft groups (as well as how to use each), head to our guide to drafting text in Ditto.
All variables are referenced by their name. Names are unique within a workspace and composed of characters in the set [A-Za-z0-9_]+.
We currently support 5 different types of variables: strings, numbers, links, lists, and maps. Depending on the type, the variable will contain different properties:
🔤 String — for dynamic text content (ex: a user's name, company name, selected value)
🔢 Number — for dynamic numbers (ex: counts, prices)
🔗 Link — for hyperlinks in the text
📜 List — for a collection of elements
➡️ Map — for key-value pairs
You can create and insert variables anywhere you can edit text in Ditto — in projects, in our Figma plugin, and in the component library!
In the edit panel, you click the "+ Insert Variable" button above the text input. Using the modal that appears, you can either create a new variable or insert an existing variable being used in your workspace. The variable will insert where you previously had your cursor.
💡 Pro Tip: If you previously had text in the text input highlighted and are creating a new variable, the text you had highlighted will pre-populate into the Example (for string/number variables) or the Text (for link variables) field. This means, you can quickly turn existing text with example values into variables by:
Once a variable has been added to the text input, you'll have to "Save Edits" to save it to the text. Variables that have been added to a selected text will display in the text and in the project area with the example value, and in a "Variables" section underneath the Edit panel outlining the variables in use and their metadata.
You can also create variables directly on the Variables page. Variables that haven't yet been used in any text are considered draft variables, and will display yellow on this page.
We built variables with the designs in mind so that dynamic content can be indicated in Ditto without affecting the legibility of mockups — allowing the mockups to still represent what the UI would look like when a user encounters it!
Variables inserted in Ditto will sync back to the design as the value that would likely get displayed in the interface itself. This means for the different variable types:
Variables in Ditto were built with the primary purpose of saving developer time, so that developers no longer have to manually interpolate their product text. Ditto provides a UI for inserting dynamic values to use in production, while also allowing non-developers to interpolate product text.
Text with variables fetched via our developer integrations (API, CLI, and JSON export) will be written with mustache interpolation. The variables used in a text item will be included as metadata in the text object in the JSON.
For example, this text item in Ditto:
Will appear like this in the string itself:
For the full and structured JSON formats, the variable metadata will also get included in the text object itself:
You can view and manage all of the variables in your workspace by opening up the Variables tab.
Here, you can search for the variable by their name, view and edit variables, as well as see all variable activity in your workspace. If a variable is not currently used in any projects/components, you can also delete it from your workspace.