Listviews API

A listview is coded as a simple unordered list (ul) or ordered list (ol) with a data-role="listview" attribute and has a wide range of features.

Read-only, unordered

A listview is a simple unordered list containing linked list items with a data-role="listview" attribute.

Read-only, ordered

Lists can also be created from ordered lists (ol) which is useful when presenting items that are in a sequence such as search results or a movie queue.

Linked

Wrapping the contents of each list item makes it clickable; a right arrow indicator makes this clear.

Inset

Adding the data-inset="true" attribute to the list (ul or ol), applies the inset appearance which is useful for mixing a listview with other content on a page.

Filter

To make a list filterable, simply add the data-filter="true" attribute to the list. The framework will then append a search box above the list and add the behavior to filter out list items that don't contain the current search string as the user types. The input's placeholder text defaults to "Filter items...". To configure the placeholder text in the search input, use the data-filter-placeholder attribute. By default the search box will inherit its theme from its parent. The search box theme can be configured using the data attribute data-filter-theme on your listview.

Filter reveal

The filter reveal feature makes it easy to build a simple autocomplete with local data. When a filterable list has the data-filter-reveal="true" attribute, it will auto-hide all the list items when the search field is blank. The data-filter-placeholder attribute can be added to specify the placeholder text for the filter. If you need to search against a long list of values, we provide a way to create a filter with a remote data source.

List dividers

List items can be turned into dividers to organize and group the list items. This is done by adding the data-role="list-divider" to any list item. These items are styled with the bar swatch "b" by default (blue in the default theme) but you can specify a theme for dividers by adding the data-divider-theme attribute to the list element (ul or ol) and specifying a theme swatch letter. You can override the divider-theme for a specific divider by adding the data-theme attribute to the list item.

Autodividers

A listview can be configured to automatically generate dividers for its items by adding a data-autodividers="true" attribute to any listview. By default, the text used to create dividers is the uppercased first letter of the item's text. Alternatively you can specify divider text by setting the autodividersSelector option on the listview programmatically. This feature is designed to work seamlessly with the filter.

Count bubbles

To add a count indicator to the right of the list item, wrap the number in an element with a class of ui-li-count. The theme for count bubbles can be set by adding the data-count-theme to the list and specifying a swatch letter.

Icons: Standard

The default icon for each list item containing a link is arrow-r. To override this, set the data-icon attribute on the desired list item to the name of a standard icon. To prevent icons from appearing altogether, set the data-icon attribute to "false". With a bit of custom styling it's also possible to use third party icons.

Icons: 16x16

To use standard 16x16 pixel icons in list items, add the class of ui-li-icon to the image element and insert 16x16 icons as img tags inside the list items.

Thumbnails

To add thumbnails to the left of a list item, simply add an image inside a list item as the first child element. The framework will scale the image to 80 pixels square.

Split buttons

To make a split list item, simply add a second link inside the li. To adjust the split button icon, add the data-split-icon attribute to the listview . Add the data-icon attribute to individual list items for more control. The theme swatch color of the split button defaults to "b" (blue in the default theme) but can be set by specifying a swatch letter with the data-split-theme attribute at the listview level or for individual splits with the data-theme attribute at the link level.

Formatted content

To add text hierarchy, use headings to increase font emphasis and use paragraphs to reduce emphasis. Supplemental information can be added to the right of each list item by wrapping content in an element with a class of ui-li-aside

Theme

The list item color scheme can be changed to any button color theme swatch by adding the data-theme attribute to the listview or to individual list items. The theme for list dividers can be set by adding the data-divider-theme to the list. The theme for count bubbles can be set by adding the data-count-theme to the list.

To specify the swatch for the split button, add the data-split-theme to the list and specify a swatch letter. This attribute can also be added to individual split inside list items by adding a data-theme attribute to specific links (see second list item). The icon for the split button can be set at the list level by adding the data-split-icon.

The white icon sprite is used by default in the theme. Adding the ui-icon-alt class to the list switches to the black sprite and gets rid of the dark disc.

Forms

Any form element can be placed inside a listview for a grouped presentation.

Collapsible listview

This is an example of a listview wrapped in a container with data-role="collapsible".

Grouped collapsible with listviews

You can also use listviews inside a collapsible set (accordion) to visually group the list and ensure that only a single item can be open at once.

Full width collapsible listview

Setting data-inset="false" on a collapsible or a collapsible set makes the collapsible full width (non-inset), like a full width listview.

Nested

By nesting child ul or ol inside list items, you can create nested lists. To set the swatch color of the child listviews, set the data-theme attribute on each list inside.

Warning: Nested listviews are deprecated as of 1.3 and will be removed in future versions.