Skip to content

Default Renderer

DefaultRenderer is the main renderer of listr2.

DefaultRenderer is intended for TTY environments with vt100 terminal compatibility, where it updates the current update constantly depending on the changes in Task. This renderer has many options for customization, these options can be changed at Listr, Subtask or Task level.

This renderer uses ProcessOutput to take control of the terminal.

demo

Renderer Options

Details

Documentation / listr2 / ListrDefaultRendererOptions

Interface: ListrDefaultRendererOptions

Inject your custom style map consisting of icons and coloring for the ListrLogger.

See

https://listr2.kilic.dev/renderer/logger.html

Extends

Properties

timer?

optional timer: PresetTimer

Show duration for the tasks.

Inherited from

RendererPresetTimer.timer

Source

packages/listr2/src/presets/timer/preset.interface.ts:9


indentation?

optional indentation: number

Indentation per-level.

  • This is a global option that can only be changed through the main Listr class.

Default Value

2

Source

packages/listr2/src/renderer/default/renderer.interface.ts:24


formatOutput?

optional formatOutput: "wrap" | "truncate"

Formats the output in to the given lines of process.stdout.columns.

  • This is a global option that can only be changed through the main Listr class.

Default Value

'wrap'

Source

packages/listr2/src/renderer/default/renderer.interface.ts:32


clearOutput?

optional clearOutput: boolean

Clear all the output generated by the renderer when the Listr completes the execution successfully.

  • This is a global option that can only be changed through the main Listr class.

Default Value

false

Source

packages/listr2/src/renderer/default/renderer.interface.ts:40


lazy?

optional lazy: boolean

Only update the render whenever there is a incoming request through the hook.

  • This is a global option that can only be changed through the main Listr class.
  • Useful for snapshot tests, where this will disable showing spinner and only update the screen if something else has happened in the task worthy to show.

Default Value

false

Source

packages/listr2/src/renderer/default/renderer.interface.ts:49


removeEmptyLines?

optional removeEmptyLines: boolean

Remove empty lines from the output section for decluterring multiple line output.

Default Value

true

Source

packages/listr2/src/renderer/default/renderer.interface.ts:55


spinner?

optional spinner: Spinner

Spinner visually indicates that a task is running.

  • You can always implement your own spinner, if the current one does not please you visually.

Source

packages/listr2/src/renderer/default/renderer.interface.ts:61


showSubtasks?

optional showSubtasks: boolean

Show the subtasks of the current task.

Default Value

true

Source

packages/listr2/src/renderer/default/renderer.interface.ts:70


collapseSubtasks?

optional collapseSubtasks: boolean

Collapse subtasks after current task completes its execution.

Default Value

true

Source

packages/listr2/src/renderer/default/renderer.interface.ts:76


showSkipMessage?

optional showSkipMessage: boolean

Show skip messages or show the original title of the task.

  • true will output the given skip message if there is any.
  • false will keep the current task title intact. This will also disable collapseSkips.

Default Value

true

Source

packages/listr2/src/renderer/default/renderer.interface.ts:88


collapseSkips?

optional collapseSkips: boolean

Collapse skip messages into a single message and overwrite the task title.

  • true will collapse skiped tasks.
  • false will show the skip message as a data output under the current task title.

Default Value

true

Source

packages/listr2/src/renderer/default/renderer.interface.ts:97


suffixSkips?

optional suffixSkips: boolean

Suffix skip messages to clearly indicate the task has been skipped with in collapseSkips mode.

  • true will add [SKIPPED] as a suffix.
  • false will not add a suffix.

Default Value

false

Source

packages/listr2/src/renderer/default/renderer.interface.ts:106


showErrorMessage?

optional showErrorMessage: boolean

Show the error message or show the original title of the task.

  • true will output the current error encountered with the task if there is any.
  • false will keep the current task title intact. This will also disable collapseErrors.

Default Value

true

Source

packages/listr2/src/renderer/default/renderer.interface.ts:118


collapseErrors?

optional collapseErrors: boolean

Collapse error messages into a single message and overwrite the task title.

  • true will collapse the error message.
  • false will show the error message as a data output under the current task title.

Default Value

true

Source

packages/listr2/src/renderer/default/renderer.interface.ts:127


suffixRetries?

optional suffixRetries: boolean

Suffix retry messages to clearly indicate the task is currently retrying.

  • true will add [RETRY:COUNT] as a suffix.
  • false will not add a suffix.

Default Value

false

Source

packages/listr2/src/renderer/default/renderer.interface.ts:139


pausedTimer?

optional pausedTimer: PresetTimer

Show duration for the pauses.

Default Value

PRESET_TIMER

Source

packages/listr2/src/renderer/default/renderer.interface.ts:148


color?

optional color: Partial<Record<ListrDefaultRendererLogLevels, LoggerFormat>>

Coloring of the levels.

See

https://listr2.kilic.dev/renderer/logger.html#style

Inherited from

ListrLoggerStyleMap.color

Source

packages/listr2/src/utils/logger/logger.interface.ts:33


icon?

optional icon: Partial<Record<ListrDefaultRendererLogLevels, string>>

Icons of the levels.

See

https://listr2.kilic.dev/renderer/logger.html#style

Inherited from

ListrLoggerStyleMap.icon

Source

packages/listr2/src/utils/logger/logger.interface.ts:39


logger?

optional logger: ListrLogger<ListrDefaultRendererLogLevels>

Inject your custom implementation of the ListrLogger.

See

https://listr2.kilic.dev/renderer/logger.html

Inherited from

RendererLoggerOptions.logger

Source

packages/listr2/src/utils/logger/logger.interface.ts:82

Renderer Task Options

Details

Documentation / listr2 / ListrDefaultRendererTaskOptions

Interface: ListrDefaultRendererTaskOptions

Extends

Properties

timer?

optional timer: PresetTimer

Show duration for the tasks.

Inherited from

RendererPresetTimer.timer

Source

packages/listr2/src/presets/timer/preset.interface.ts:9


outputBar?

optional outputBar: number | boolean

Write task output to the output bar under the title.

  • true only keep the last line.
  • Infinity will keep all the lines.
  • number will keep the defined amount of lines.
  • false will not render output with this method.

Default Value

true

Source

packages/listr2/src/renderer/default/renderer.interface.ts:162


bottomBar?

optional bottomBar: number | boolean

Write task output to the bottom bar instead of the gap under the task title itself. This can be useful for stream of data coming in and is the default mode for tasks without a title.

This will take precedence over the outputBar option, if explicitly set.

  • true only keep the last line.
  • Infinity will keep all the lines.
  • number will keep the defined amount of lines.
  • false will not render output with this method.

Default Value

false

Source

packages/listr2/src/renderer/default/renderer.interface.ts:176


persistentOutput?

optional persistentOutput: boolean

Keep output of the task after task finishes.

  • This can be enabled for both normal task output under the title and bottom bar.

Default Value

ts
false

Source

packages/listr2/src/renderer/default/renderer.interface.ts:184