Customization options for CarUiListItem

This page details the customization options for CarUiListItem list items.

The accepted paradigm for using the Car UI library to display a list of items is to use a CarUiRecyclerView in conjunction with a CarUiListItemAdapter and CarUiListItem objects. CarUiRecyclerView customization is covered in caruirecyclerview.

Prerequisites

The following content presumes an understanding of runtime resource overlays (RRO) described in Customize apps.

About CarUiListItem

List items can be one of two high-level types, header or content. Each is described below.

CarUiListItemAdapter binds objects of type CarUiHeaderListItem to a view inflated from the car_ui_header_list_item layout file, which contains these views:

Views
title Title TextView
body Body TextView

For example, the header list item below is configured to display a title and body text:

Content

CarUiListItemAdapter binds objects of type CarUiHeaderListItem to a view inflated from the car_ui_list_item layout file. This file contains these views:

Views
icon_container Container for the primary icon
title Title TextView
body Body TextView
action_container Container for the action view

For example, the content list item below was configured to display an icon and a switch:

Icons

Depending on the icon type configured for the list item, one of the following three views is used for the primary icon:

Views
icon Standard icon ImageView
content_icon Content icon ImageView
avatar_icon Avatar icon ImageView

Action elements

At most, one of the following action element views is displayed, based on the action type for the list item:

Views
switch_widget Switch
checkbox_widget CheckBox
radio_button_widget RadioButton
supplemental_icon ImageView

Customize text

Text styling in both header and content list items is controlled by text appearances styles defined in the Car UI library. To override the text styling of list items, override the corresponding styles listed below.

To customize header styles:

Header styles
Title text @style/TextAppearance.CarUi.ListItem
Body text @style/TextAppearance.CarUi.ListItem.Body

To customize content styles:

Content styles
Title text @style/TextAppearance.CarUi.ListItem.Header
Body text @style/TextAppearance.CarUi.ListItem.Body

Customize icons

Content list items can contain both a primary and a supplemental icon.

Primary icon

Although there are three ImageView objects defined within the icon container in the content list item layout, at most one icon is displayed based on the list item's specified icon type. At item bind time, CarUiListItemAdapter sets the appropriate visibility for the icon ImageView objects.

The width and height of icons are controlled by dimension values that can be overlaid to control the sizing. The dimension values that specify the width and height for the various icon types are listed below.

Standard icon

By default, standard icons have equal height and width.

Standard icon
Width car_ui_list_item_icon_size
Height car_ui_list_item_icon_size

Content icon

Content icon
Width car_ui_list_item_content_icon_width
Height car_ui_list_item_content_icon_height

Avatar icon

By default, primary icons are centered within the icon container view, which has a width defined by the car_ui_list_item_icon_container_width dimension value.

Avatar icon
Width car_ui_list_item_content_icon_width
Height car_ui_list_item_content_icon_height

Supplemental icon

The supplemental icon is centered within the action container view. Both the width and height of the supplemental icon are defined by the car_ui_list_item_supplemental_icon_size dimension value. Overlay this dimension value to change the size of the supplemental icon.