# Reference option

Learn how to define reference options for templates.

Reference options accept a variable name rather than a literal value, allowing an imported template to read and write a variable from the caller's scope.

By default, [imported](/reference/cli/templates/actions/import) templates run in their own scope and cannot access the caller's variables. A reference option creates a shared binding between the two scopes, so the imported template can read the current value and write back changes that the caller will see.

## Example

Consider a utility template that converts a variable to uppercase. It receives the variable name through the `target` option and uses bracket notation to access it:

**to-upper.json5**

```json5
{
  "$schema": "https://schema.croct.com/json/v1/template.json",
  "title": "To uppercase",
  "description": "Converts a variable value to uppercase.",
  "options": {
    "target": {
      "type": "reference",
      "description": "The variable to convert."
    }
  },
  "actions": [
    {
      "name": "define",
      "variables": {
        "${options.target}": "${this[options.target].toUpperCase()}"
      }
    }
  ]
}
```

Here, `options.target` holds the variable *name* (e.g., `"greeting"`), and `this[options.target]` reads the current *value* of that variable. Because `target` is a reference option, the imported template shares access to the caller's variable.

The following template imports `to-upper.json5` to transform a greeting:

**template.json5**

```json5
{
  "$schema": "https://schema.croct.com/json/v1/template.json",
  "title": "Greeting",
  "description": "Prints an uppercase greeting.",
  "options": {
    "name": {
      "type": "string",
      "description": "The name to greet.",
      "default": "World"
    }
  },
  "actions": [
    {
      "name": "define",
      "variables": {
        "greeting": "Hello, ${options.name}!"
      }
    },
    {
      "name": "import",
      "template": "./to-upper.json5",
      "options": {
        "target": "greeting"
      }
    },
    {
      "name": "print",
      "semantics": "info",
      "message": "${this.greeting}"
    }
  ]
}
```

```sh
npx croct@latest use template.json5 --name Alice
```

This prints `HELLO, ALICE!`. The imported template reads `this.greeting` from the caller's scope, converts it to uppercase, and writes the result back. If `target` were a regular string option instead, the imported template would not be able to access or modify the caller's variable.

## Properties

The following list describes the properties for reference options:

- `type`: `string`

  The option type. Always `reference` for reference options.

- `description`: `string`

  A description displayed when prompting the user.

- `default`: `string` (optional)

  The default variable name used when the user does not provide one.

## Explore

- [Options overview](/reference/cli/templates/options/overview): Learn how template options work.
- [Variables](/reference/cli/templates/variables): Explore the built-in template variables.
