# SectionedItemTemplate.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/SectionedItemTemplate.java+class:androidx.car.app.model.SectionedItemTemplate.Builder) Added in [1.7.0](https://developer.android.com/jetpack/androidx/releases/car-app#1.7.0)

*** ** * ** ***


```
public final class SectionedItemTemplate.Builder
```

<br />

*** ** * ** ***

A builder that constructs `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate` instances.

Upon building, this class validates the following:

- The template is not both loading and populated with sections
- Only `https://developer.android.com/reference/androidx/car/app/model/ChipSection`, `https://developer.android.com/reference/androidx/car/app/model/RowSection`, `https://developer.android.com/reference/androidx/car/app/model/GridSection`, `https://developer.android.com/reference/androidx/car/app/model/CondensedSection`, or `https://developer.android.com/reference/androidx/car/app/model/BannerSection` are added as sections
- If a `https://developer.android.com/reference/androidx/car/app/model/ChipSection` is added, it must be the first section and only one is allowed

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#Builder()()` Create a new `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate` builder. |
| `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#Builder(androidx.car.app.model.SectionedItemTemplate)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate template)` Create a new `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate` builder, copying the values from an existing instance. |

| ### Public methods |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.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 single `https://developer.android.com/reference/androidx/car/app/model/Action` to this template, appending to the existing list of actions. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#addSection(androidx.car.app.model.Section<?>)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/Section<@https://developer.android.com/reference/androidx/annotation/NonNull ?> section)` Adds a single `https://developer.android.com/reference/androidx/car/app/model/Section` to this template, appending to the existing list of sections. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate` | `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#build()()` Constructs a new `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate` from the current state of this builder, throwing exceptions for any invalid state. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#clearActions()()` Removes all actions in this template. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#clearSections()()` Removes all sections from this template. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setActions(java.util.List<androidx.car.app.model.Action>)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/List.html<https://developer.android.com/reference/androidx/car/app/model/Action> actions)` Sets the actions that show up alongside the sections of this template (as opposed to the actions in the header), overwriting any other previously set actions from `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#addAction(androidx.car.app.model.Action)` or `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setActions(java.util.List<androidx.car.app.model.Action>)`. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html [setAlphabeticalIndexingAllowed](https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setAlphabeticalIndexingAllowed(boolean))(boolean alphabeticalIndexingAllowed)` **This method is deprecated.** use `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setAlphabeticalIndexingStrategy(int)` instead. <br /> |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setAlphabeticalIndexingStrategy(int)(int alphabeticalIndexingStrategy)` Sets how this list can be indexed alphabetically. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setHeader(androidx.car.app.model.Header)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/car/app/model/Header header)` Sets or clears the optional header for this template. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setLoading(boolean)(boolean isLoading)` Sets whether or not this 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/SectionedItemTemplate.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setScrollStatePersistenceStrategy(int)(int scrollStatePersistenceStrategy)` Set how to handle a user's scroll position when this template is used as a refresh of another `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate`. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | `@https://developer.android.com/reference/androidx/car/app/annotations/ExperimentalCarApi @https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 9) @https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setSearchHeader(androidx.car.app.model.SearchHeader)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/car/app/model/SearchHeader searchHeader)` Sets or clears a search header on this template, enabling search input mode. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | `@https://checkerframework.org/api/com/google/errorprone/annotations/CanIgnoreReturnValue.html https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setSections(java.util.List<androidx.car.app.model.Section<?>>)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/util/List.html<https://developer.android.com/reference/androidx/car/app/model/Section<@https://developer.android.com/reference/androidx/annotation/NonNull ?>> sections)` Sets the sections in this template, overwriting any other previously set sections. |

## Public constructors

### Builder

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

```
public Builder()
```

Create a new `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate` builder.

### Builder

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

```
public Builder(@NonNull SectionedItemTemplate template)
```

Create a new `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate` builder, copying the values from an existing instance.

## Public methods

### addAction

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

```
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder addAction(@NonNull Action action)
```

Adds a single `https://developer.android.com/reference/androidx/car/app/model/Action` to this template, appending to the existing list of actions. All actions must conform to the constraints.

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.

### addSection

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

```
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder addSection(@NonNull Section<@NonNull ?> section)
```

Adds a single `https://developer.android.com/reference/androidx/car/app/model/Section` to this template, appending to the existing list of sections. Only sections listed in `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` can be added.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | for a list of allowed section types |

### build

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

```
public @NonNull SectionedItemTemplate build()
```

Constructs a new `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate` from the current state of this builder, throwing exceptions for any invalid state.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | for the list of validation logic |

### clearActions

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

```
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder clearActions()
```

Removes all actions in this template.

### clearSections

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

```
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder clearSections()
```

Removes all sections from this template.

### setActions

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

```
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setActions(@NonNull List<Action> actions)
```

Sets the actions that show up alongside the sections of this template (as opposed to the actions in the header), overwriting any other previously set actions from `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#addAction(androidx.car.app.model.Action)` or `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setActions(java.util.List<androidx.car.app.model.Action>)`. All actions must conform to the constraints.

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.

### setAlphabeticalIndexingAllowed

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

```
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder [setAlphabeticalIndexingAllowed](https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setAlphabeticalIndexingAllowed(boolean))(boolean alphabeticalIndexingAllowed)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> use `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setAlphabeticalIndexingStrategy(int)` instead. This method will default to setting `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate#ALPHABETICAL_INDEXING_TITLE_IGNORE_ARTICLES_AND_SYMBOLS()`.

Sets whether this list can be indexed alphabetically, by item title. By default, this is `false`.

"Indexing" refers to the process of examining list contents (e.g. item titles) to sort, partition, or filter a list. Indexing is generally used for features called "Accelerators", which allow a user to quickly find a particular `https://developer.android.com/reference/androidx/car/app/model/Item` in a long list.

For example, a media app may, by default, show a user's playlists sorted by date created. If the app provides these playlists via the `SectionedItemTemplate` and enables `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate#isAlphabeticalIndexingAllowed()`, the user will be able to jump to their playlists that start with the letter "H". When this happens, the list is reconstructed and sorted alphabetically, then shown to the user, jumping down to the letter "H".

Individual items may be excluded from the list by setting their `#isIndexable` field to `false`.

### setAlphabeticalIndexingStrategy

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

```
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setAlphabeticalIndexingStrategy(int alphabeticalIndexingStrategy)
```

Sets how this list can be indexed alphabetically. By default, this is `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate#ALPHABETICAL_INDEXING_DISABLED()`.

"Indexing" refers to the process of examining list contents (e.g. item titles) to sort, partition, or filter a list. Indexing is generally used for features called "Accelerators", which allow a user to quickly find a particular `https://developer.android.com/reference/androidx/car/app/model/Item` in a long list.

For example, a media app may, by default, provide a user's playlists sorted by date created in `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#addSection(androidx.car.app.model.Section<?>)`. If `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#setAlphabeticalIndexingStrategy(int)` is set to a non-disabled value, the user will be able to jump to their playlists that start with the letter "H". When this happens, the list is reconstructed and sorted alphabetically, then shown to the user, jumping down to the letter "H".

Individual items may be excluded from the reconstructed list by setting their `#isIndexable` field to `false`.

### setHeader

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

```
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setHeader(@Nullable Header header)
```

Sets or clears the optional header for this template.

Note that only one of `https://developer.android.com/reference/androidx/car/app/model/Header` or `https://developer.android.com/reference/androidx/car/app/model/SearchHeader` can be set on this template at the same time. Otherwise, an exception will be thrown on `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#build()` invocation.

### setLoading

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

```
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setLoading(boolean isLoading)
```

Sets whether or not this template is in a loading state. If passed `true`, sections cannot be added to the template. By default, this is `false`.

### setScrollStatePersistenceStrategy

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

```
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setScrollStatePersistenceStrategy(int scrollStatePersistenceStrategy)
```

Set how to handle a user's scroll position when this template is used as a refresh of another `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate`.

For example, if a user is currently scrolled down to item 10 in an existing `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate`, setting this field to `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate#SCROLL_STATE_PRESERVE_INDEX()` would cause the user to be shown item 10 from this template. Alternatively, `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate#SCROLL_STATE_RESET_TO_TOP()` would cause the user to be reset to the top of this template.

By default, this is set to `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate#SCROLL_STATE_RESET_TO_TOP()`.

### setSearchHeader

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

```
@ExperimentalCarApi
@RequiresCarApi(value = 9)
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setSearchHeader(@Nullable SearchHeader searchHeader)
```

Sets or clears a search header on this template, enabling search input mode.

Note that only one of `https://developer.android.com/reference/androidx/car/app/model/Header` or `https://developer.android.com/reference/androidx/car/app/model/SearchHeader` can be set on this template at the same time. Otherwise, an exception will be thrown on `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder#build()` invocation.

### setSections

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

```
@CanIgnoreReturnValue
public @NonNull SectionedItemTemplate.Builder setSections(@NonNull List<Section<@NonNull ?>> sections)
```

Sets the sections in this template, overwriting any other previously set sections. Only sections listed in `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` can be added.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/car/app/model/SectionedItemTemplate.Builder` | for a list of allowed section types |