# prompt

Learn how to request input from the user.

This action prompts the user for input and stores the response in a variable.

It supports different prompt types for collecting text, selections, confirmations, and keypress events.

## Example

The following template asks the user to confirm before opening a link:

**template.json5**

```json5
{
  "$schema": "https://schema.croct.com/json/v1/template.json",
  "title": "Open docs",
  "description": "Asks whether to open the documentation.",
  "actions": [
    {
      "name": "prompt",
      "type": "confirmation",
      "message": "Open the documentation in the browser?",
      "default": true,
      "result": "shouldOpen"
    },
    {
      "name": "test",
      "condition": "${this.shouldOpen}",
      "then": [
        {
          "name": "open-link",
          "url": "https://docs.croct.com"
        }
      ]
    }
  ]
}
```

To apply this template, run:

```sh
croct use template.json5
```

### Text input

Use the `text` type to collect free-form input:

**template.json5**

```json5
{
  "$schema": "https://schema.croct.com/json/v1/template.json",
  "title": "Project namer",
  "description": "Asks for a project name.",
  "actions": [
    {
      "name": "prompt",
      "type": "text",
      "message": "What is the project name?",
      "default": "my-app",
      "required": true,
      "result": "projectName"
    },
    {
      "name": "print",
      "semantics": "info",
      "message": "Project name: ${this.projectName}"
    }
  ]
}
```

### Selection

Use the `choice` type to present a list of options:

**template.json5**

```json5
{
  "$schema": "https://schema.croct.com/json/v1/template.json",
  "title": "Framework selector",
  "description": "Asks the user to choose a framework.",
  "actions": [
    {
      "name": "prompt",
      "type": "choice",
      "message": "Which framework are you using?",
      "options": [
        {
          "value": "next",
          "label": "Next.js"
        },
        {
          "value": "remix",
          "label": "Remix"
        },
        {
          "value": "astro",
          "label": "Astro"
        }
      ],
      "default": "next",
      "result": "framework"
    },
    {
      "name": "print",
      "semantics": "info",
      "message": "Selected: ${this.framework}"
    }
  ]
}
```

A selection list is displayed. The user picks an option with arrow keys and presses Enter to confirm.

### Keypress

Use the `keypress` type to pause execution until the user presses a key:

**template.json5**

```json5
{
  "$schema": "https://schema.croct.com/json/v1/template.json",
  "title": "Pause example",
  "description": "Pauses execution until the user presses a key.",
  "actions": [
    {
      "name": "print",
      "semantics": "info",
      "message": "Review the changes above before continuing."
    },
    {
      "name": "prompt",
      "type": "keypress",
      "message": "Press any key to continue"
    }
  ]
}
```

## Properties

These are the supported properties:

- `name`: `string`

  The action identifier. Always `prompt` for this action.

- `type`: `string`

  The type of prompt to display.

  | Type           | Result type | Description                       |
  | -------------- | ----------- | --------------------------------- |
  | `confirmation` | boolean     | A yes/no prompt.                  |
  | `text`         | string      | A free-form text input.           |
  | `choice`       | string      | A single selection from a list.   |
  | `multi-choice` | string list | A multiple selection from a list. |
  | `keypress`     | string      | Waits for a key press.            |

- `message`: `string`

  The message to display to the user.

- `result`: `string`

  The variable name to store the user's response.

  The type of the stored value depends on the prompt type, as shown in the table above. Optional for `keypress` prompts.

- `default`: `boolean | string` (optional)

  The default value if the user does not provide input.

  For `confirmation` prompts, this is a boolean. For `text` and `choice` prompts, this is a string. Not available for `multi-choice` or `keypress`.

- `initial`: `string` (optional)

  The initial value pre-filled in the input field.

  Unlike `default`, which is used when running non-interactively, `initial` populates the input field for the user to edit. If both are set, `default` takes precedence.

  Used with `text` prompts.

- `required`: `boolean` (optional) (default: false)

  Whether the input is required.

  When enabled, empty submissions are rejected.

  Used with `text` prompts.

- `options`: `Array<string> | Array<object>` (optional)

  The list of options to choose from.

  Each option can be a string, which is used as both the value and label, or an object with the following properties:

  - `value`: `string`

    The value stored when the option is selected.

  - `label`: `string` (optional)

    The display text for the option.

    Defaults to the value if omitted.

  - `disabled`: `boolean` (optional) (default: false)

    Whether the option is disabled.

  - `selected`: `boolean` (optional) (default: false)

    Whether the option is pre-selected.

    Used with `multi-choice` prompts.

  Used with `choice` and `multi-choice` prompts.

- `min`: `number` (optional)

  The minimum number of selections.

  Used with `multi-choice` prompts.

- `max`: `number` (optional)

  The maximum number of selections.

  Used with `multi-choice` prompts.

- `key`: `string` (optional)

  The specific key to wait for.

  Supported values are `enter`, `space`, or a single character. If omitted, any key is accepted.

  Used with `keypress` prompts.

## Explore

- [Print](/reference/cli/templates/actions/print): Learn how to print a message to the user.
- [Define](/reference/cli/templates/actions/define): Learn how to store a value without prompting.
- [Test](/reference/cli/templates/actions/test): Learn how to branch based on user input.
- [Open link](/reference/cli/templates/actions/open-link): Learn how to open a URL in the browser.