inquirer-form-prompt

A prompt for inquirer that presents a form with multiple fields and form-like interaction

Install

pnpm add inquirer-form-prompt
yarn add inquirer-form-prompt
npm add inquirer-form-prompt

Usage

At minimum, the prompt config must include message: string and fields: Array<Field>

Example:

import form from 'inquirer-form-prompt'

const answer = await form({
    message: 'Trip Details',
    fields: [
        {
            label: 'Full name',
            type: 'text',
        },
        {
            label: 'Transport type',
            type: 'radio',
            choices: ['Train', 'Flight', 'Bus'],
            value: 'Train',
        },
        {
            label: 'Activities',
            type: 'checkbox',
            choices: ['Museums', 'Local Cuisine', 'Historical Sites', 'Nightlife', 'Nature & Parks'],
            value: ['Museums', 'Local Cuisine'],
            description: 'What activities interest you most? (Select all that apply)',
        },
    ],
})

Tip

See src/demo.ts for a more thorough example. Try it with pnpm demo.

Fields

All fields take the following properties:

label: string // The input field's label
description?: string // Help text that will appear when the field is focused

Text

Use this field for strings, numbers, and free entry. Users may also paste from the clipboard when this field is focused.

type: 'text'
value?: string // Optional default value

Example:

{
    label: 'Full name',
    type: 'text',
    description: 'As it appears on your passport'
}

Boolean

Use this field for true-or-false entry.

The left and right arrow keys move between the two options. Pressing the spacebar selects or deselects that option.

type: 'boolean'
value?: boolean // Optional default value

Example:

{
    label: 'Do you need a visa?',
    type: 'boolean',
}

Radio button options (select one)

Use this field when the user must choose exactly one option.

The left and right arrow keys move the selection.

type: 'radio'
choices: Array<string>
value?: boolean // Optional default value, must match one of the choices

Example:

{
    label: 'Age group',
    type: 'radio',
    choices: ['0-25', '26-50', '51-75', '76-100']
    description: 'In years, on the first day of travel'
}

Check box options (multiple selection)

Use this field when the user may choose multiple options.

The left and right arrow keys move between options. Pressing the spacebar selects or deselects an option. When the form is submitted, only the selected values will be returned.

type: 'checkbox'
choices: Array<string>
value?: Array<string> // Optional default value, each string must match one of the choices

Example:

{
    label: 'Activities of Interest',
    type: 'checkbox',
    choices: ['Museums & Art', 'Local Cuisine', 'Historical Sites', 'Nightlife', 'Nature & Parks'],
    value: ['Museums & Art', 'Local Cuisine'],
}

Grouping fields

Fields may be split into groups by placing separators between them in the fields array. See examples below.

Theming

The config object accepts a theme prop which can be used to specify a variant.

theme?: {
    variant: 'table' | 'label-top'
    dense?: boolean
}

Table

This is the default theme. Each field label and input is displayed in a table row. If a separator is included, it will split the fields into separate tables.

In this example, "Trip Details" and "Preferences" are both separators:

Label Top

With this variant, the label is displayed above the input field. If a separator is included, it will split the fields into separate tables.

This variant also supports a dense option which removes some of the extra spacing around the fields:

theme: {
    variant: 'label-top',
    dense: true
}

Footer

The config object accepts an optional footer prop which is a function that receives the current field values and returns a string to display below the form. The footer updates in real-time as the user fills in the form.

footer?: (values: ReturnedItems) => string

Example:

import form, { ReturnedItems } from 'inquirer-form-prompt'
import { Separator } from '@inquirer/core'

const answer = await form({
    message: 'User Profile',
    fields: [
        {
            label: 'Name',
            type: 'text',
            value: '',
        },
        {
            label: 'Age',
            type: 'text',
            value: '',
        },
    ],
    footer: (values: ReturnedItems) => {
        const name = values.find((v) => !(v instanceof Separator) && v.label === 'Name')
        const age = values.find((v) => !(v instanceof Separator) && v.label === 'Age')
        const nameValue = name && !(name instanceof Separator) && name.value ? name.value : 'Unknown'
        const ageValue = age && !(age instanceof Separator) && age.value ? age.value : '?'
        return `Profile: ${nameValue} (${ageValue} years old)`
    },
})

This is useful for showing summaries, validation hints, or computed values based on the current form state.