listr2

Appearance

Fallback Condition ​

There are times other than non-TTY environments when you want to fallback to a fallback/silent renderer than the selected renderer.

A function that returns a boolean , or directly a boolean can be passed to Listr for automatically stepping down to the fallbackRenderer or directly to SilentRenderer when the condition is met.

Behavior ​

TTY or non-TTY Environment ​

fallbackRenderer will be automatically used whenever you are in a non-TTY environment.

  • You can force to use TTY environment via Listr option forceTTY or set the environment variable LISTR_FORCE_TTY=1.

Coloring ​

colorette is used as the underlying coloring library. Colors are disabled automatically by underlying the library whenever it is detected as not supported.

  • You can set the environment variable FORCE_COLOR=1 to force colors.
  • You can set the environment variable NO_COLOR=1 to disable colors completely even though your environment supports it. This is very useful for tests.

Unicode ​

Unicode characters like icons are not used whenever it is detected that your output does not support them.

  • You can use the forceUnicode option on Listr or set the environment variable LISTR_FORCE_UNICODE=1 to force the usage of the Unicode characters.

WARNING

These checks are primal at best but do not forget that in many cases, your terminal might support any of these UI properties, but the application in between might abstract access to them therefore it can be detected otherwise.

Usage ​

Example

You can find the related examples here.

Renderer Fallback ​

You can use the fallbackRendererCondition condition on Listr to determine changing your renderer to the fallback renderer.

ts
import { delay, Listr } from 'listr2'

const tasks = new Listr(
  [
    {
      title: 'This task will execute.',
      task: async (ctx, task): Promise<void> => {
        task.output = 'test'

        await delay(500)
      },
      rendererOptions: { persistentOutput: true }
    }
  ],
  { concurrent: false, fallbackRendererCondition: (): boolean => 3 < 1 }
)

await tasks.run()

Silent Renderer Fallback ​

You can use the silentRendererCondition condition on Listr to determine changing your renderer to the fallback renderer.

ts
import { delay, Listr } from 'listr2'

const tasks = new Listr(
  [
    {
      title: 'This task will execute.',
      task: async (ctx, task): Promise<void> => {
        task.output = 'test'

        await delay(500)
      },
      rendererOptions: { persistentOutput: true }
    }
  ],
  { concurrent: false, silentRendererCondition: (): boolean => 3 < 1 }
)

await tasks.run()