TTY::Prompt

You can prevent specific items from being selected by providing a :disabled key. This is useful for items that are out of stock or otherwise unavailable. Disabled choices are visually marked with a ✘ character and the reason provided in the :disabled value is displayed next to the choice name.

In an array of hashes:

choices = [
  {name: "small", value: 1},
  {name: "medium", value: 2, disabled: "(out of stock)"}
]

In a DSL block:

menu.choice "medium", 2, disabled: "(out of stock)"

To start using tty-prompt, require the library and initialize a new prompt instance. You can then use various methods to gather user input.

require "tty-prompt"

prompt = TTY::Prompt.new

# Simple text input
name = prompt.ask("What is your name?", default: "Piotr")

# Boolean confirmation
likes_ruby = prompt.yes?("Do you like Ruby?")

# Masked input (for passwords/secrets)
secret = prompt.mask("What is your secret?")

# Single selection from a list
choice = prompt.select("Choose your destiny?", %w(Scorpion Kano Jax))

# Multiple selection from a list
drinks = prompt.multi_select("Select drinks?", %w(vodka beer wine))

You can install tty-prompt using one of the following methods:

Using Bundler

Add the following line to your Gemfile:

gem "tty-prompt"

Then run:

$ bundle

Using Gem

Install it directly via the command line:

$ gem install tty-prompt

To disable all ANSI color output for a prompt, pass enable_color: false to the TTY::Prompt constructor.

prompt = TTY::Prompt.new(enable_color: false)

By default, hitting Control-C raises an InputInterrupt error. You can customize this behavior using the :interrupt option in TTY::Prompt.new.

Available options:

• :signal: Sends an interrupt signal.
• :exit: Exits the program with a status code.
• :noop: Skips the handler (no action taken).
• custom proc: A custom block to handle the interrupt.

prompt = TTY::Prompt.new(interrupt: :signal)

You can customize the symbols used by various prompts (like ticks, crosses, or markers) by passing a :symbols hash to TTY::Prompt.new. This allows you to switch between Unicode and ASCII characters for better compatibility or aesthetic preference.

Available symbols to overwrite:

• tick (default: ✓ / √)
• cross (default: ✘ / x)
• marker (default: ‣ / >)
• dot (default: • / .)
• bullet (default: ● / O)
• line (default: ─ / -)
• radio_on (default: ⬢ / (*))
• radio_off (default: ⬡ / ( ))
• arrow_up (default: ↑)
• arrow_down (default: ↓)
• arrow_left (default: ←)
• arrow_right (default: →)

prompt = TTY::Prompt.new(symbols: {marker: ">"})

Prompts that accept line input (like multiline or ask) track a history buffer by default, allowing users to navigate previous entries using the up/down arrow keys. To disable this behavior, set track_history: false in the TTY::Prompt constructor.

prompt = TTY::Prompt.new(track_history: false)

You can add a consistent prefix to every question asked by the prompt instance using the :prefix option. This can be set globally or for individual prompts.

prompt = TTY::Prompt.new(prefix: "[?] ")

The :help_color option allows you to change the color of help text (e.g., instructions on how to use arrow keys). This is supported by select, multi_select, and expand prompts.

Like :active_color, it can be applied globally or per-prompt and accepts a color symbol, a Pastel object, or a callable.

The :active_color option controls the color used to highlight currently selected choices in select, multi_select, enum_select, and expand prompts, as well as the user's final answer.

This can be set globally during initialization or individually for a specific prompt call. The value can be a color symbol, a Pastel object, or a callable (proc).

Supported colors can be found in the pastel documentation.