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

*** ** * ** ***

<br />

```
public final class SearchTemplate.Builder
```

<br />

*** ** * ** ***

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

## Summary

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder#Builder(androidx.car.app.model.SearchTemplate.SearchCallback)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.SearchCallback callback)` Returns a new instance of a `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder` with the input `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.SearchCallback`. |

| ### Public methods |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SearchTemplate` | `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder#build()()` Constructs the `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate` model. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.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)` Sets the `https://developer.android.com/reference/androidx/car/app/model/ActionStrip` for this template. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.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)` Sets the `https://developer.android.com/reference/androidx/car/app/model/Action` that will be displayed in the header of the template. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder#setInitialSearchText(java.lang.String)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html initialSearchText)` Sets the initial search text to display in the search box. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder#setItemList(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 itemList)` Sets the `https://developer.android.com/reference/androidx/car/app/model/ItemList` to show for search results. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.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/SearchTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder#setSearchHint(java.lang.String)(@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/java/lang/String.html searchHint)` Sets the text hint to display in the search box when it is empty. |
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder` | `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder#setShowKeyboardByDefault(boolean)(boolean showKeyboardByDefault)` Sets if the keyboard should be displayed by default, instead of waiting until user interacts with the search box. |

## Public constructors

### Builder

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

```
public Builder(@NonNull SearchTemplate.SearchCallback callback)
```

Returns a new instance of a `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder` with the input `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.SearchCallback`.

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

| Parameters |
|---|---|
| `@https://jspecify.dev/docs/api/org/jspecify/annotations/NonNull.html https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.SearchCallback callback` | the callback to be invoked for events such as when the user types new text, or submits a search |

## Public methods

### build

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

```
public @NonNull SearchTemplate build()
```

Constructs the `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate` model.

| Throws |
|---|---|
| `https://developer.android.com/reference/java/lang/IllegalArgumentException.html` | if the template is in a loading state but the list is set |

### setActionStrip

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

```
public @NonNull SearchTemplate.Builder setActionStrip(@NonNull ActionStrip actionStrip)
```

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

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` |

### setHeaderAction

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

```
public @NonNull SearchTemplate.Builder setHeaderAction(@NonNull Action headerAction)
```

Sets the `https://developer.android.com/reference/androidx/car/app/model/Action` that will be displayed in the header of the template.

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` |

### setInitialSearchText

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

```
public @NonNull SearchTemplate.Builder setInitialSearchText(@NonNull String initialSearchText)
```

Sets the initial search text to display in the search box.

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

### setItemList

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

```
public @NonNull SearchTemplate.Builder setItemList(@NonNull ItemList itemList)
```

Sets the `https://developer.android.com/reference/androidx/car/app/model/ItemList` to show for search results.

The list will be shown below the search box, allowing users to click on individual search results.

#### 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. The list itself cannot be selectable as set via `https://developer.android.com/reference/androidx/car/app/model/ItemList.Builder#setOnSelectedListener(androidx.car.app.model.ItemList.OnSelectedListener)`. Each `https://developer.android.com/reference/androidx/car/app/model/Row` can add up to 2 lines of texts via `https://developer.android.com/reference/androidx/car/app/model/Row.Builder#addText(java.lang.CharSequence)` and cannot contain a `https://developer.android.com/reference/androidx/car/app/model/Toggle`.

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

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

### setLoading

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

```
public @NonNull SearchTemplate.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 shows the `https://developer.android.com/reference/androidx/car/app/model/ItemList` contents added via `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder#setItemList(androidx.car.app.model.ItemList)`.

### setSearchHint

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

```
public @NonNull SearchTemplate.Builder setSearchHint(@NonNull String searchHint)
```

Sets the text hint to display in the search box when it is empty.

The host will use a default search hint if not set with this method.

This is not the actual search text, and will disappear if user types any value into the search.

If a non empty text is set via `https://developer.android.com/reference/androidx/car/app/model/SearchTemplate.Builder#setInitialSearchText(java.lang.String)`, the `searchHint ` will not show, unless the user erases the search text.

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

### setShowKeyboardByDefault

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

```
public @NonNull SearchTemplate.Builder setShowKeyboardByDefault(boolean showKeyboardByDefault)
```

Sets if the keyboard should be displayed by default, instead of waiting until user interacts with the search box.

Defaults to `true`.