Title

Task can have a title to stand out from the crowd and give the user visual queues of what is actually running.

Usage

The title of the Task can be initiated while creating the task itself and, can be directly manipulated through the injected task object during runtime.

This allows the user to change the title depending on the progress made throughout the task, or simply to inform the user that the task is finished.

import { delay, Listr } from 'listr2'

const tasks = new Listr([
  {
    title: 'Doing some stuff...',
    task: async(ctx, task): Promise<void> => {
      await delay(1000)

      task.title = 'I have done stuff, but should do some more.'

      await delay(1000)

      task.title = 'All the stuff has been done.'
    }
  }
])

await tasks.run()

Tasks without a Title

The title of a Task is an optional property.

For most of the renderers, except for TestRenderer, the tasks that do not have a title would be hidden. For something like a default renderer tasks that have subtasks with no title will be flattened visually.

You can always use task.title programmatically to add titles, and visually pop tasks to existence.

Code Example

import { delay, Listr } from 'listr2'

const tasks = new Listr([
  {
    task: async(ctx, task): Promise<void> => {
      await delay(1000)

      task.title = 'I have done stuff, but should do some more.'

      await delay(1000)

      task.title = 'All the stuff has been done.'
    }
  },
  {
    task: async(ctx, task): Promise<void> => {
      await delay(1000)

      task.title = 'I am popping in to existence.'

      await delay(1000)

      task.title = 'Hey yo I am done!'
    }
  }
])

await tasks.run()

Remove the Title #793

Setting the title to undefined or null removes it, and the Task is treated as a task without a title until a new title is assigned.

task.title = undefined

task.output = null

This emits a dedicated TITLE_RESET task event instead of a TITLE event, so the TITLE event always carries a string. Combined with resetting the output, this hides a Task from view without changing the renderer options for the rest of the tasks.

WARNING

Prior to this, task.title = undefined used to render the literal string "undefined".