inquirer-form-prompt

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

Install

``sh
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

Example:

`tsx
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:

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

$3

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

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

Example:

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

$3

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.

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

Example:

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

$3

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

The left and right arrow keys move the selection.

`tsx
type: 'radio'
choices: Array
value?: boolean // Optional default value, must match one of the choices
`

Example:

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

$3

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.

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

Example:

`tsx
{
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.

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

$3

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:

$3

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:

`tsx
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.

`tsx
footer?: (values: ReturnedItems) => string
`

Example:

`tsx
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.