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

*** ** * ** ***


```
public final class GridItem.Builder
```

<br />

*** ** * ** ***

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

## Summary

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

| ### Public methods |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/GridItem` | `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#build()()` Constructs the `https://developer.android.com/reference/androidx/car/app/model/GridItem` defined by this builder. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder` | `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setImage(androidx.car.app.model.CarIcon)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/CarIcon image)` Sets an image to show in the grid item with the default size `https://developer.android.com/reference/androidx/car/app/model/GridItem#IMAGE_TYPE_LARGE()`. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder` | `@https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 8) https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setImage(androidx.car.app.model.CarIcon,androidx.car.app.model.Badge)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/CarIcon image, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/Badge badge)` Sets an image to show in the grid item with the given `https://developer.android.com/reference/androidx/car/app/model/Badge` to be displayed over the image, with the default size `https://developer.android.com/reference/androidx/car/app/model/GridItem#IMAGE_TYPE_LARGE()`. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder` | `[setImage](https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setImage(androidx.car.app.model.CarIcon,int))(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/CarIcon image, int imageType)` **This method is deprecated.** Use `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setImage(androidx.car.app.model.CarIcon)` instead. <br /> |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder` | `@https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 8) [setImage](https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setImage(androidx.car.app.model.CarIcon,int,androidx.car.app.model.Badge))(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/CarIcon image, int imageType, @https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/Badge badge)` **This method is deprecated.** Use `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setImage(androidx.car.app.model.CarIcon,androidx.car.app.model.Badge)` instead. <br /> |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder` | `@https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 8) https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setIndexable(boolean)(boolean indexable)` Sets whether this item can be included in indexed lists. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder` | `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setLoading(boolean)(boolean isLoading)` Sets whether the item is in a loading state. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder` | `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setOnClickListener(androidx.car.app.model.OnClickListener)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/OnClickListener onClickListener)` Sets the `https://developer.android.com/reference/androidx/car/app/model/OnClickListener` to be called back when the grid item is clicked, or `null` to make the grid item non-clickable. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder` | `@https://developer.android.com/reference/androidx/car/app/annotations/RequiresCarApi(value = 9) @https://developer.android.com/reference/androidx/car/app/annotations/ExperimentalCarApi https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setProgressBar(androidx.car.app.model.CarProgressBar)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/CarProgressBar progressBar)` Sets the progress bar to display in the grid item. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder` | `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setText(androidx.car.app.model.CarText)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/CarText text)` Sets a secondary text string to the grid item that is displayed below the title, with support for multiple length variants. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder` | `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setText(java.lang.CharSequence)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/CharSequence.html text)` Sets a secondary text string to the grid item that is displayed below the title. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder` | `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setTitle(androidx.car.app.model.CarText)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/androidx/car/app/model/CarText title)` Sets the title of the `https://developer.android.com/reference/androidx/car/app/model/GridItem`, with support for multiple length variants. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder` | `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setTitle(java.lang.CharSequence)(@https://jspecify.dev/docs/api/org/jspecify/annotations/Nullable.html https://developer.android.com/reference/java/lang/CharSequence.html title)` Sets the title of the `https://developer.android.com/reference/androidx/car/app/model/GridItem`. |

## 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/GridItem.Builder` instance.

## Public methods

### build

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

```
public @NonNull GridItem build()
```

Constructs the `https://developer.android.com/reference/androidx/car/app/model/GridItem` defined by this builder.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if the grid item's image is set when it is loading or vice versa, if the grid item is loading but the click listener is set, or if a badge is set and an image is not set |
| `https://developer.android.com/reference/java/lang/IllegalStateException.html` | if both `mText` and `mProgressBar` are set |

### setImage

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

```
public @NonNull GridItem.Builder setImage(@NonNull CarIcon image)
```

Sets an image to show in the grid item with the default size `https://developer.android.com/reference/androidx/car/app/model/GridItem#IMAGE_TYPE_LARGE()`.

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

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setImage(androidx.car.app.model.CarIcon,int)` |   |

### setImage

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

```
@RequiresCarApi(value = 8)
public @NonNull GridItem.Builder setImage(@NonNull CarIcon image, @NonNull Badge badge)
```

Sets an image to show in the grid item with the given `https://developer.android.com/reference/androidx/car/app/model/Badge` to be displayed over the image, with the default size `https://developer.android.com/reference/androidx/car/app/model/GridItem#IMAGE_TYPE_LARGE()`.

A dot badge denotes some sort of call to action or notification and is displayed in the upper right corner of the image. An icon badge gives additional context about the image and is displayed in the lower right corner.

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

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setImage(androidx.car.app.model.CarIcon,int)` |   |

### setImage

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

```
public @NonNull GridItem.Builder [setImage](https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setImage(androidx.car.app.model.CarIcon,int))(@NonNull CarIcon image, int imageType)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> Use `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setImage(androidx.car.app.model.CarIcon)` instead. Tint is controlled directly by `https://developer.android.com/reference/androidx/car/app/model/CarIcon`, and image size is controlled by the parent template or section (e.g. `https://developer.android.com/reference/androidx/car/app/model/GridSection.Builder#setItemSize(int)`).

Sets an image to show in the grid item with the given `imageType`.

For a custom `https://developer.android.com/reference/androidx/car/app/model/CarIcon`, its `https://developer.android.com/reference/androidx/core/graphics/drawable/IconCompat` instance can be of `https://developer.android.com/reference/androidx/core/graphics/drawable/IconCompat#TYPE_BITMAP()`, `https://developer.android.com/reference/androidx/core/graphics/drawable/IconCompat#TYPE_RESOURCE()`, or `https://developer.android.com/reference/androidx/core/graphics/drawable/IconCompat#TYPE_URI()`.

#### Image Sizing Guidance

If the input image's size exceeds the sizing requirements for the given image type in either one of the dimensions, it will be scaled down to be centered inside the bounding box while preserving its aspect ratio.

See `https://developer.android.com/reference/androidx/car/app/model/CarIcon` for more details related to providing icon and image resources that work with different car screen pixel densities.

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/CarIcon image` | the `https://developer.android.com/reference/androidx/car/app/model/CarIcon` to display |
| `int imageType` | one of `https://developer.android.com/reference/androidx/car/app/model/GridItem#IMAGE_TYPE_ICON()` or `https://developer.android.com/reference/androidx/car/app/model/GridItem#IMAGE_TYPE_LARGE()` |

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

### setImage

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

```
@RequiresCarApi(value = 8)
public @NonNull GridItem.Builder [setImage](https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setImage(androidx.car.app.model.CarIcon,int,androidx.car.app.model.Badge))(@NonNull CarIcon image, int imageType, @NonNull Badge badge)
```

> [!CAUTION]
> **This method is deprecated.**   
>
> Use `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setImage(androidx.car.app.model.CarIcon,androidx.car.app.model.Badge)` instead. Tint is controlled directly by `https://developer.android.com/reference/androidx/car/app/model/CarIcon`, and image size is controlled by the parent template or section (e.g. `https://developer.android.com/reference/androidx/car/app/model/GridSection.Builder#setItemSize(int)`).

Sets an image to show in the grid item with the given `imageType` and given `https://developer.android.com/reference/androidx/car/app/model/Badge` to be displayed over the image.

A dot badge denotes a call to action or notification and is displayed in the upper right corner of the image. An icon badge gives additional context about the image and is displayed in the lower right corner.

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

### setIndexable

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

```
@RequiresCarApi(value = 8)
public @NonNull GridItem.Builder setIndexable(boolean indexable)
```

Sets whether this item can be included in indexed lists. By default, this is set to `true`.

The host creates indexed lists to help users navigate through long lists more easily by sorting, filtering, or some other means.

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 `#isAlphabeticalIndexingAllowed`, the user will be able to select a letter on a keyboard to jump to their playlists that start with that letter. When this happens, the list is reconstructed and sorted alphabetically, then shown to the user, jumping down to the letter. Items that are set to `#setIndexable(false)`, do not show up in this new sorted list. Sticking with the media example, a media app may choose to hide things like "autogenerated playlists" from the list and only keep user created playlists.

Individual items can be set to be included or excluded from filtered lists, but it's also possible to enable/disable the creation of filtered lists as a whole via the template's API (eg. `SectionedItemTemplate
.Builder#setAlphabeticalIndexingStrategy(int)`).

### setLoading

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

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

Sets whether the item is in a loading state.

If set to `true`, the UI shows a loading indicator where the grid item 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 shows the item contents.

### setOnClickListener

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

```
public @NonNull GridItem.Builder setOnClickListener(@NonNull OnClickListener onClickListener)
```

Sets the `https://developer.android.com/reference/androidx/car/app/model/OnClickListener` to be called back when the grid item is clicked, or `null` to make the grid item non-clickable.

Note that the listener relates to UI events and will be executed on the main thread using `https://developer.android.com/reference/android/os/Looper.html#getMainLooper()`

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

### setProgressBar

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

```
@RequiresCarApi(value = 9)
@ExperimentalCarApi
public @NonNull GridItem.Builder setProgressBar(@NonNull CarProgressBar progressBar)
```

Sets the progress bar to display in the grid item.

**Note:** This field is mutually exclusive with `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setText(java.lang.CharSequence)`. If both are set, `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#build()` will throw an `https://developer.android.com/reference/java/lang/IllegalStateException.html`.

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

### setText

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

```
public @NonNull GridItem.Builder setText(@NonNull CarText text)
```

Sets a secondary text string to the grid item that is displayed below the title, with support for multiple length variants.

`text` must conform to in Car API 7 and below, and in Car API 8 and above.

## Text Wrapping

This text is truncated at the end to fit in a single line below the title

**Note:** This field is mutually exclusive with `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setProgressBar(androidx.car.app.model.CarProgressBar)`. If both are set, `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#build()` will throw an `https://developer.android.com/reference/java/lang/IllegalStateException.html`.

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

### setText

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

```
public @NonNull GridItem.Builder setText(@NonNull CharSequence text)
```

Sets a secondary text string to the grid item that is displayed below the title.

`text` must conform to in Car API 7 and below, and in Car API 8 and above.

## Text Wrapping

This text is truncated at the end to fit in a single line below the title

**Note:** This field is mutually exclusive with `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#setProgressBar(androidx.car.app.model.CarProgressBar)`. If both are set, `https://developer.android.com/reference/androidx/car/app/model/GridItem.Builder#build()` will throw an `https://developer.android.com/reference/java/lang/IllegalStateException.html`.

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

### setTitle

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

```
public @NonNull GridItem.Builder setTitle(@Nullable CarText title)
```

Sets the title of the `https://developer.android.com/reference/androidx/car/app/model/GridItem`, with support for multiple length variants.

`title` must conform to in Car API 7 and below, and in Car API 8 and above.

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

### setTitle

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

```
public @NonNull GridItem.Builder setTitle(@Nullable CharSequence title)
```

Sets the title of the `https://developer.android.com/reference/androidx/car/app/model/GridItem`.

`title` must conform to in Car API 7 and below, and in Car API 8 and above.

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