‍

Variables

‍

What are variables?

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.

‍

Variable Basics

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)‍

• Example — an example of a value for the variable. The example value is what will get synced back to the design.‍
• Fallback (optional) — a value that can be used in production if no value is provided for the variable (ex: a generic word like "user" instead of a name or an explicit fallback like "N/A").

🔢 Number — for dynamic numbers (ex: counts, prices)

• Example — an example of a value for the variable. The example value is what will get synced back to the design. For numbers, this must be a number (characters in the set [0-9.]+).
• Fallback (optional) — a value that can be used in production if no value is provided for the variable (ex: a generic word like "a few" instead of a numeric count or an explicit fallback like "N/A").

🔗 Link — for hyperlinks in the text

• Text — the text that's linked itself. This value is what will get synced back to the design.‍
• URL — the actual URL to be linked for this text. Must be a full URL.

📜 List — for a collection of elements

• Value — an element in the collection. A list can have as many values as you'd like. All values need to be unique.

➡️ Map — for key-value pairs

• Key-Value Pair — each key maps back to a specified value. A map can have as many key-value pairs as you'd like. All keys need to be unique.

‍

Creating Variables

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:

1. Highlighting the dynamic value
2. Pressing "+ Insert Variable" to turn it into a variable!

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.

‍

🎨 Syncing with designs

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:

• String or Number — the "Example" field is what shows in the mockups
• Hyperlink — the "Text" field is what shows in the mockups
• List or Map —the first "Value" field is what shows in the mockups

‍

💻 How developers can use variables?

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:

{
	"text": "Hello, {{firstName}}! You have {{cartCount}} items in your cart. Click {{cartLink}} to view them all.",
	"variables": {
		"firstName": {
			"example": "Stacy",
			"fallback": "user"
		},
		"cartCount": {
			"example": 10,
			"fallback": "no"
		}
		"cartLink": {
			"text": "here",
			"url": "myshop.com/checkout"
		}
	}
	... //additional fields like notes, status, and tags will still get included as usual
}

‍

🛠 Managing Variables

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.