---
url: https://listr2.kilic.dev/renderer/logger.md
---

# {{ $frontmatter.title }}

[ListrLogger](/api/listr2/classes/ListrLogger.html) is a common interface that enables the renderers to have a certain output format.

*ListrLogger* is used for every renderer to a certain degree. *ListrLogger* is a middleware between the console outputs of the renderers and handles the output streams `stdout` and `stderr` through *ProcessOutput*, and it might take full control of those streams while the renderer is rendering to avoid something else trying to write to the terminal. *ListrLogger* also handles the styling and formatting of to be dumped data to the terminal depending on their level, which includes the colors and styling.

## Log Levels

Log levels for the *ListrLogger* are dynamically injected while creating an instance of *ListrLogger* and will affect the styling section of the instance.

By default, [ListrLogLevels](/api/listr2/enumerations/ListrLogLevels.html) is used for text-based renderers. For renderers like *DefaultRenderer* styling require more cases than usual compared to the text-based renderers, therefore custom log levels [ListrDefaultRendererListrLogLevels](/api/listr2/enumerations/ListrDefaultRendererListrLogLevels.html) are injected.

## Style

The *style* of *ListrLogger* can be customized through [ListrLoggerOptions](/api/listr2/interfaces/ListrLoggerOptions.html). Since every renderer in some form is using *ListrLogger* this functionality can be used to customize the renderers directly without implementing your renderer.

### Icons and Colors

*ListrLogger* can be customized for any renderer through the exposed fields on your renderer inside the respective renderer options that use the *ListrLogger*.

The `icon` and `color` section of the supported renderer is in the form of [ListrLoggerStyleMap](/api/listr2/interfaces/ListrLoggerStyleMap.html). By injecting new style options into the *ListrLogger* you can change the icons and colors of every possible task.

::: details  Code Example

<<< @../../examples/docs/renderer/style/icon-and-color.ts

:::

## Fields

*ListrLogger* can wrap each entry with fields in the form of prefixes and suffixes through `logger.prefix(message, ...fields)` and `logger.suffix(message, ...fields)`. A field is either a plain `string` or a [`LoggerField`](/api/listr2/type-aliases/LoggerField.html) object, which can compute its value from arguments, render conditionally, and carry its own formatting.

```typescript
logger.suffix('a message', { field: () => new Date().toISOString(), condition: showTimestamp })
```

The [presets](#presets) below are prebuilt fields — timers and timestamps — that plug into this same prefix/suffix mechanism.

## Presets

The Preset mechanism is used for displaying additional data like [timestamps](/api/listr2/variables/PRESET_TIMESTAMP.html) or [timers](/api/listr2/variables/PRESET_TIMER.html). This also gives flexibility to making things dynamic with a conditional display of fields or conditional styling.

Different renderers support different presets, depending on whether it fits in the style of the selected renderer. Presets are not directly tied with the *ListrLogger* itself but it is mostly leveraging the mechanism to have fields in the sense of prefixes and suffixes in the logging entry.

You can either pass the predefined preset to a given field or override a preset's behavior by overwriting the fields of the preset since it is designed as an object.

### Preset Timer

This preset can be used to show how much time has elapsed for a given thing to happen.

This preset is available for the *DefaultRenderer*, *VerboseRenderer*, and *SimpleRenderer* on both *Listr* and *Task* level options.

::: details  Code Example

<<< @../../examples/docs/renderer/logger/preset-timer.ts

:::

### Preset Timestamp

This preset can be used to stamp log entries with the current timestamp.

This preset is available for the *VerboseRenderer*, *SimpleRenderer* on *Listr* level options.

::: details  Code Example

<<< @../../examples/docs/renderer/logger/preset-timestamp.ts

:::

## Custom Logger

You can use your custom *ListrLogger* whenever the underlying renderer is using it directly. This argument is always true for the provided renderers that output to the console.

To do this you must expand the original *ListrLogger* implementation since it is again a stateful class.

::: details  Code Example

<<< @../../examples/docs/renderer/logger/custom-implementation.ts

:::

> After a couple of attempts with , this turned out to be the most flexible solution for modifying the logger, where it is shared with multiple different implementations of renderers, and they do not use it the same way.

::: warning

Some options for the *ListrLogger* are forcefully injected through the selected renderer. These are the options like global field options like `timestamp` or `icon` and `style` options, to expose them without requiring a custom logger since this falls into the more advanced use cases.

:::