> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skyvexsoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ctx.prompt

> Blocking prompts that ask the pilot for a text, number, or selected value, from a background module.

`ctx.prompt` asks the pilot for a value via a blocking modal and returns it. Each method resolves to the entered value, or `null` if the pilot cancels (Cancel, dismiss, `timeoutMs`, or the plugin being unloaded). The shell renders the modal; your plugin only describes it. For acknowledgement or a yes/no decision, use [`ctx.dialog`](/sdk/background/context/dialog) instead.

## `text()`

Ask for a string.

```ts theme={null}
const gate = await ctx.prompt.text({
  title: "Departure gate",
  label: "What gate are you departing from?",
  placeholder: "e.g. A12",
  required: true,
});
if (gate === null) return; // pilot cancelled
```

## `number()`

Ask for a number, with optional `min` / `max`.

```ts theme={null}
const fuel = await ctx.prompt.number({
  title: "Fuel",
  label: "Block fuel (kg)",
  min: 0,
});
```

## `select()`

Ask the pilot to choose from a list. Resolves to the chosen option's `value`.

```ts theme={null}
const runway = await ctx.prompt.select({
  title: "Runway",
  label: "Departure runway",
  options: [
    { value: "27L", label: "27L" },
    { value: "27R", label: "27R" },
  ],
});
```

## Return values & cancellation

| Method              | Returns                                        |
| ------------------- | ---------------------------------------------- |
| `ctx.prompt.text`   | `Promise<string \| null>`                      |
| `ctx.prompt.number` | `Promise<number \| null>`                      |
| `ctx.prompt.select` | `Promise<string \| null>` (the option `value`) |

A valid submit returns the value; Cancel, dismiss, `timeoutMs`, or the plugin being unloaded all return `null`. These calls never throw on cancellation, so you don't need `try/catch`.

All three accept an optional `timeoutMs` (absent by default — waits until answered or dismissed). Set it for non-critical prompts so a forgotten dialog can't pin the pilot's screen. Prompts are shown one at a time. Awaiting a prompt inside `onStop` will not resolve (the app is shutting down).

**When to use it:** when your background logic needs a value from the pilot before continuing — a gate number, block fuel, a runway. Keep these rare; for anything that doesn't need an answer use [`ctx.notify`](/sdk/background/context/notify).