# ListTemplate.Builder

Artifact: [androidx.car.app:app](https://developer.android.com/jetpack/androidx/releases/car-app) [View Source](https://cs.android.com/search?q=file:androidx/car/app/model/ListTemplate.java+class:androidx.car.app.model.ListTemplate.Builder) Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

*** ** * ** ***


```
public final class ListTemplate.Builder
```

<br />

*** ** * ** ***

A builder of `https://developer.android.com/reference/androidx/car/app/model/ListTemplate`.

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#Builder()()` Returns an empty `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder` instance. |

| ### Public methods |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder` | `@https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 6) https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#addAction(androidx.car.app.model.Action)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/Action action)` Adds a template scoped action outside the rows. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#addSectionedList(androidx.car.app.model.SectionedItemList)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemList list)` Adds an `https://developer.android.com/reference/androidx/car/app/model/SectionedItemList` to display in the template. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ListTemplate` | `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#build()()` Constructs the template defined by this builder. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#clearSectionedLists()()` Clears all of the `https://developer.android.com/reference/androidx/car/app/model/SectionedItemList`s added via `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#addSectionedList(androidx.car.app.model.SectionedItemList)` |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder` | `[setActionStrip](https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#setActionStrip(androidx.car.app.model.ActionStrip))(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ActionStrip actionStrip)` **This method is deprecated.** Use `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#addEndHeaderAction(androidx.car.app.model.Action)` <br /> |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder` | `@https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 7) https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#setHeader(androidx.car.app.model.Header)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/Header header)` Sets the `https://developer.android.com/reference/androidx/car/app/model/Header` for this template. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder` | `[setHeaderAction](https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#setHeaderAction(androidx.car.app.model.Action))(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/Action headerAction)` **This method is deprecated.** Use `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#setStartHeaderAction(androidx.car.app.model.Action)` <br /> |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#setLoading(boolean)(boolean isLoading)` Sets whether the template is in a loading state. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#setSingleList(androidx.car.app.model.ItemList)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ItemList list)` Sets a single `https://developer.android.com/reference/androidx/car/app/model/ItemList` to show in the template. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder` | `[setTitle](https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#setTitle(java.lang.CharSequence))(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/CharSequence.html title)` **This method is deprecated.** Use `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#setTitle(androidx.car.app.model.CarText)` <br /> |

## Public constructors

### Builder

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public Builder()
```

Returns an empty `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder` instance.

## Public methods

### addAction

Added in [1.4.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.4.0)

```
@RequiresCarApi(value = 6)
public @NonNull ListTemplate.Builder addAction(@NonNull Action action)
```

Adds a template scoped action outside the rows.

Note: Starting in Car API 9, for media apps (apps with `https://developer.android.com/reference/androidx/car/app/CarAppPermission#MEDIA_TEMPLATES()`), a maximum of 1 action can be set, as the host reserves space to render a persistent media entry point or miniplayer. If extra actions are sent by a media app, the host will drop the extra action.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `action` contains unsupported Action types, or does not contain a valid `https://developer.android.com/reference/androidx/car/app/model/CarIcon` and background `https://developer.android.com/reference/androidx/car/app/model/CarColor`, or if exceeds the maximum number of allowed actions for the template. |

| See also |
|---|---|
| `androidx.car.app.model.constraints.ActionsConstraints.ACTIONS_CONSTRAINTS_FAB` |   |

### addSectionedList

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public @NonNull ListTemplate.Builder addSectionedList(@NonNull SectionedItemList list)
```

Adds an `https://developer.android.com/reference/androidx/car/app/model/SectionedItemList` to display in the template.

Use this method to add multiple lists to the template. Each `https://developer.android.com/reference/androidx/car/app/model/SectionedItemList` will be grouped under its header. These lists cannot be mixed with an `https://developer.android.com/reference/androidx/car/app/model/ItemList` added via `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#setSingleList(androidx.car.app.model.ItemList)`. If a single list was previously added, it will be cleared.

If the added `https://developer.android.com/reference/androidx/car/app/model/SectionedItemList` contains a `https://developer.android.com/reference/androidx/car/app/model/ItemList.OnSelectedListener`, then it cannot be added alongside other `https://developer.android.com/reference/androidx/car/app/model/SectionedItemList`(s).

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if `list` or `header` is `null` |
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `list` is empty, if `list`'s `https://developer.android.com/reference/androidx/car/app/model/ItemList.OnItemVisibilityChangedListener` is set, if `header` is empty, or if a selectable list is added alongside other lists |

### build

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public @NonNull ListTemplate build()
```

Constructs the template defined by this builder.

#### Requirements

The number of items in the `https://developer.android.com/reference/androidx/car/app/model/ItemList` should be smaller or equal than the limit provided by `https://developer.android.com/reference/androidx/car/app/constraints/ConstraintManager#CONTENT_LIMIT_TYPE_LIST()`. The host will ignore any items over that limit. Each `https://developer.android.com/reference/androidx/car/app/model/Row`s can add up to 2 lines of texts via `https://developer.android.com/reference/androidx/car/app/model/Row.Builder#addText(java.lang.CharSequence)`.

If none of the header `https://developer.android.com/reference/androidx/car/app/model/Action`, the header title or the action strip have been set on the template, the header is hidden.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if the template is in a loading state but there are lists added or vice versa |
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if the added `https://developer.android.com/reference/androidx/car/app/model/ItemList`(s) do not meet the template's requirements |

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/car/app/constraints/ConstraintManager#getContentLimit(int)` |   |

### clearSectionedLists

Added in [1.3.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.3.0)

```
public @NonNull ListTemplate.Builder clearSectionedLists()
```

Clears all of the `https://developer.android.com/reference/androidx/car/app/model/SectionedItemList`s added via `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#addSectionedList(androidx.car.app.model.SectionedItemList)`

### setActionStrip

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0) Deprecated in [1.7.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.7.0)

```
public @NonNull ListTemplate.Builder [setActionStrip](https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#setActionStrip(androidx.car.app.model.ActionStrip))(@NonNull ActionStrip actionStrip)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> Use `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#addEndHeaderAction(androidx.car.app.model.Action)`

Sets the `https://developer.android.com/reference/androidx/car/app/model/ActionStrip` for this template or `null` to not display an `https://developer.android.com/reference/androidx/car/app/model/ActionStrip`.

Unless set with this method, the template will not have an action strip.

#### Requirements

This template allows up to 2 `https://developer.android.com/reference/androidx/car/app/model/Action`s in its `https://developer.android.com/reference/androidx/car/app/model/ActionStrip`. Of the 2 allowed `https://developer.android.com/reference/androidx/car/app/model/Action`s, one of them can contain a title as set via `https://developer.android.com/reference/androidx/car/app/model/Action.Builder#setTitle(java.lang.CharSequence)`. Otherwise, only `https://developer.android.com/reference/androidx/car/app/model/Action`s with icons are allowed.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `actionStrip` does not meet the requirements |
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if `actionStrip` is `null` |

### setHeader

Added in [1.7.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.7.0)

```
@RequiresCarApi(value = 7)
public @NonNull ListTemplate.Builder setHeader(@NonNull Header header)
```

Sets the `https://developer.android.com/reference/androidx/car/app/model/Header` for this template.

The end header actions will show up differently inside vs outside of a map template. See `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#addEndHeaderAction(androidx.car.app.model.Action)` for more details.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if `header` is null |

### setHeaderAction

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0) Deprecated in [1.7.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.7.0)

```
public @NonNull ListTemplate.Builder [setHeaderAction](https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#setHeaderAction(androidx.car.app.model.Action))(@NonNull Action headerAction)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> Use `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#setStartHeaderAction(androidx.car.app.model.Action)`

Sets the `https://developer.android.com/reference/androidx/car/app/model/Action` that will be displayed in the header of the template, or `null` to not display an action.

Unless set with this method, the template will not have a header action.

#### Requirements

This template only supports either one of `https://developer.android.com/reference/androidx/car/app/model/Action#APP_ICON()` and `https://developer.android.com/reference/androidx/car/app/model/Action#BACK()` as a header `https://developer.android.com/reference/androidx/car/app/model/Action`.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `headerAction` does not meet the template's requirements |
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if `headerAction` is `null` |

### setLoading

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public @NonNull ListTemplate.Builder setLoading(boolean isLoading)
```

Sets whether the template is in a loading state.

If set to `true`, the UI will display a loading indicator where the list content would be otherwise. The caller is expected to call `https://developer.android.com/reference/androidx/car/app/Screen#invalidate()` and send the new template content to the host once the data is ready.

If set to `false`, the UI will display the contents of the `https://developer.android.com/reference/androidx/car/app/model/ItemList` instance(s) added via `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#setSingleList(androidx.car.app.model.ItemList)` or `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#addSectionedList(androidx.car.app.model.SectionedItemList)`.

### setSingleList

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0)

```
public @NonNull ListTemplate.Builder setSingleList(@NonNull ItemList list)
```

Sets a single `https://developer.android.com/reference/androidx/car/app/model/ItemList` to show in the template.

Note that this list cannot be mixed with others added via `https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#addSectionedList(androidx.car.app.model.SectionedItemList)` . If multiple lists were previously added, they will be cleared.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if `list` is null |

### setTitle

Added in [1.0.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.0.0) Deprecated in [1.7.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.7.0)

```
public @NonNull ListTemplate.Builder [setTitle](https://developer.android.com/reference/androidx/car/app/model/ListTemplate.Builder#setTitle(java.lang.CharSequence))(@NonNull CharSequence title)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> Use `https://developer.android.com/reference/androidx/car/app/model/Header.Builder#setTitle(androidx.car.app.model.CarText)`

Sets the title of the template.

Unless set with this method, the template will not have a title.

Only `https://developer.android.com/reference/androidx/car/app/model/DistanceSpan`s and `https://developer.android.com/reference/androidx/car/app/model/DurationSpan`s are supported in the input string.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/NullPointerException.html` | if `title` is null |
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if `title` contains unsupported spans |