Listview

API Documentation

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.

  • Acura
  • Audi
  • BMW
  • Cadillac
  • Ferrari

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.

  1. Acura
  2. Audi
  3. BMW
  4. Cadillac
  5. Ferrari

Linked

List items with links are styled as button.

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

The listview can be used in conjunction with the filterable widget.

Filter reveal

The filter reveal feature of the Filterable widget makes it easy to build a simple autocomplete with local data. When the Filterable widget is instantiated on a list that has the data-filter-reveal="true" attribute, it will auto-hide all the list items when the search field is blank. 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-listview-item-count-bubble. The theme for count bubbles is inherited from the parent list item.

Icons: Standard

The default icon for each list item containing a link is caret-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-listview-item-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.

Purchase Album?

Your download will begin immediately on your mobile device when you purchase.

Buy: $10.99 Cancel

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-listview-item-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 is inherited from the parent list item.

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-alt-icon 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".

Choose a car model...

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.

Filtered list

Formatted text

Thumbnails and split button

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.

Mailbox

Calendar

Contacts