---
url: https://listr2.kilic.dev/task/subtasks.md
---

# {{ $frontmatter.title }}

`listr2` can be infinitely nested by utilizing subtasks, which is the core part of the design.

A *Task* can return a new *Listr*. But rather than calling it by invoking a `new Listr` to get the full auto-completion features depending on the parent task's selected renderer, it is mandatory to call it through the *Task* itself by `task.newListr()` since they are sharing components internally that makes the application tick.

Subtasks can be nested indefinitely as long as the terminal width is enough to support them.

Subtasks give the advantage of grouping similar tasks, changing the behavior of *Listr* for a certain set of tasks, or cleaning up the rendering area when certain tasks have finished.

## Usage

<<< @../../examples/docs/task/subtasks/usage.ts{8}

::: info Example

You can find the related examples [here](https://github.com/listr2/listr2/tree/master/examples/subtasks.example.ts).

:::

## Overwriting the Default Behavior Through Subtask Options

You can change the behavior of *Listr*, and the selected renderer of the parent through the options of a subtask.

This includes selected renderer options as well as **Listr** options like `exitOnError`, `concurrent` to be set per-subtaskly independent of the parent task, while it will always **inherit the defaults from the parent task**.

Due to design limitations of making renderers a bit simpler, some of the options that cannot be changed from the renderer are marked as `@global` in the hover documentation. This is not disabled through typings due to keeping the renderer instances fully self-contained.

::: details  Code Example

<<< @../../examples/docs/task/subtasks/overwriting-options.ts{8,23,30,45}

:::

## Access Parent Task from Subtasks

You can access the parent task class from subtasks by passing the function signature `(parent) => Listr` to `task.newListr`. This way you can change the title of the parent task or access its functionality.

::: details  Code Example

<<< @../../examples/docs/task/subtasks/access-parent-task.ts{9,15}

:::

## Renderer

### *DefaultRenderer*

Subtasks are rendered as an indented block under the parent task and can be collapsed once finished through the `collapseSubtasks` renderer option.

### *SimpleRenderer* & *VerboseRenderer*

The non-TTY renderers have no nesting area to collapse; each subtask's state changes are logged inline as they happen, in the order they run.