{"title":"Theme variables","slug":"theme-variables","url":"https://support.storeconnect.com/articles/theme-variables","url_markdown":"https://support.storeconnect.com/articles/theme-variables.md","subtitle":null,"summary":"Create key-value theme variables to make your theme configurable without editing template code. Access variables in Liquid with the theme_variables global and override built-in defaults per store.","type":"Developer_Documentation","video_url":"","keywords":"theme variables, key-value pairs, theme configuration, liquid, theme_variables, global variable, dot notation, override defaults, configurable theme, template configuration, theme settings","last_modified":"2026-08-21T07:12:35+0000","body_markdown":"Variables are key-value pairs that you can use to provide configuration options for your theme.\n\nYou can add theme variables from the Related tab of your Theme.\n\nHere we have a Key field. This must be unique per Theme. It can be anything you like, however it is good practice to use a naming convention, eg. group related items together using dot notation: `locations.search.default_distance`.\n\n![Theme variables list on the Related tab of a Theme, showing existing key-value pairs](https://res.cloudinary.com/hzkr6fi81/image/upload/v1725790510/knowledge/themes/theme-variables_e3unvd.png)\n\n![New theme variable form with a Key field for entering a unique variable name](https://res.cloudinary.com/hzkr6fi81/image/upload/v1725790516/knowledge/themes/new-variable_wpnprs.png)\n\n## When to use Theme Variables\n\nTheme variables are best used when you are creating a theme but want to give some configuration options that affect some aspect of the theme, so that the theme can be tweaked without having to alter the template code.\n\n### Example\n\nThe example theme variable `locations.search.default_distance` is a real-world example of a variable from our built-in theme. It’s used in the Location Finder liquid template to set the default search radius for the location search.\n\nWe are aware that each Store that uses our built-in theme may want to have a different default distance for the search. So we provided a variable that can be used to change this distance.\n\n## When Creating Themes\n\nTheme authors will use variables when they are aware that the end-users of their themes may want to configure some aspect slightly differently. They should extract that value into a variable and provide a good default value for the variable.\n\n## When Configuring Themes\n\nThose who are using and configuring existing themes with variables can just adjust the value of the variable. If you are configuring one of the built-in themes, you will need to create a matching variable in your theme and set the value to whatever you need. This is how you override built-in theme variables.\n\n## Using the theme variable in liquid code\n\nTheme variables can be accessed using the global variable `theme_variables`.\n\n### Example\n\nOnce again using our example variable, this is how you access its value:\n\n\n```liquid\n\n{{ theme_variables[\"locations.search.default_distance\"] }}\n```\n\n\nResult:\n\n```text\n\n50\n```"}