# jQuery Mobile

Navigation Home

# 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. Jump to section

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

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

- Acura
- Audi
- BMW
- Cadillac
- Ferrari

## 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.

- Acura
- Audi
- BMW
- Cadillac
- Ferrari

## 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.

- Apple
- Banana
- Cherry
- Cranberry
- Grape
- Orange

## Filter reveal

The filter reveal feature makes is 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.

- Apple
- Banana
- Cherry
- Cranberry
- Grape
- Orange

## 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.

- Mail
- Inbox
- Outbox
- Contacts
- Friends
- Work

## 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.

- Adam Kinkaid
- Alex Wickerham
- Avery Johnson
- Bob Cabot
- Caleb Booth
- Christopher Adams
- Culver James

## 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.

- Inbox 12
- Outbox 0
- Drafts 4
- Sent 328
- Trash 62

## 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 styles it's also possible to use third party icons.

- custom-icon
- data-icon="delete"
- data-icon="gear"
- data-icon="info"
- data-icon="false"

## 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` tage inside the list items.

- France
- Germany
- Great Britain
- Finland
- United States

## 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.

- ## Broken Bells

  Broken Bells

- ## Warning

  Hot Chip

- ## Wolfgang Amadeus Phoenix

  Phoenix

## 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.

- ## Broken Bells

  Broken Bells

  Purchase album

- ## Warning

  Hot Chip

  Purchase album

- ## Wolfgang Amadeus Phoenix

  Phoenix

  Purchase album

### 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-li-aside`

- Friday, October 8, 2010 2

- ## Stephen Weber

  You've been invited to a meeting at Filament Group in Boston, MA

  Hey Stephen, if you're available at 10am tomorrow, we've got a meeting with the jQuery team.

  6:24PM

- ## jQuery Team

  Boston Conference Planning

  In preparation for the upcoming conference in Boston, we need to start gathering a list of sponsors and speakers.

  9:18AM

- Thursday, October 7, 2010 1

- ## Avery Walker

  Re: Dinner Tonight

  Sure, let's plan on meeting at Highland Kitchen at 8:00 tonight. Can't wait!

  4:48PM

## 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.

- Divider
- Inbox 12
- Outbox 0
- Sent 328

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

- ## Broken Bells

  Purchase album

- ## Phoenix

  Purchase album

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.

- Acura
- Audi
- BMW
- Cadillac
- Ferrari

## Forms

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

- Text Input:
- Textarea:
- Flip switch:
- Slider:
- Choose shipping method:

## Collapsible listview

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

## Choose a car model...

- Acura
- Audi
- BMW
- Cadillac
- Chrysler
- Dodge
- Ferrari
- Ford
- GMC
- Honda

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

- Adam Kinkaid
- Alex Wickerham
- Avery Johnson
- Bob Cabot
- Caleb Booth

## Formatted text

- Friday, October 8, 2010 2

- ### Stephen Weber

  You've been invited to a meeting at Filament Group in Boston, MA

  Hey Stephen, if you're available at 10am tomorrow, we've got a meeting with the jQuery team.

  6:24PM

- ### jQuery Team

  Boston Conference Planning

  In preparation for the upcoming conference in Boston, we need to start gathering a list of sponsors and speakers.

  9:18AM

## Thumbnails and split button

- ### Broken Bells

  Broken Bells

  Purchase album

- ### Warning

  Hot Chip

  Purchase album

- ### Wolfgang Amadeus Phoenix

  Phoenix

  Purchase album

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

- Inbox 12
- Outbox 0
- Drafts 4
- Sent 328
- Trash 62

## Calendar

- Friday, October 8, 2010 2

- ### Stephen Weber

  You've been invited to a meeting at Filament Group in Boston, MA

  Hey Stephen, if you're available at 10am tomorrow, we've got a meeting with the jQuery team.

  6:24PM

- ### jQuery Team

  Boston Conference Planning

  In preparation for the upcoming conference in Boston, we need to start gathering a list of sponsors and speakers.

  9:18AM

- Thursday, October 7, 2010 1

- ### Avery Walker

  Re: Dinner Tonight

  Sure, let's plan on meeting at Highland Kitchen at 8:00 tonight. Can't wait!

  4:48PM

- Wednesday, October 6, 2010 3

- ### Amazon.com

  4-for-3 Books for Kids

  As someone who has purchased children's books from our 4-for-3 Store, you may be interested in these featured books.

  12:47PM

## Contacts

- Adam Kinkaid
- Alex Wickerham
- Avery Johnson
- Bob Cabot
- Caleb Booth
- Christopher Adams
- Culver James

## 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.

- Animals
  - Pets
    - Canary
    - Cat
    - Dog
  - Farm animals
    - Chicken
    - Cow
    - Sheep
  - Wild animals>
    - Alligator
    - Bear
    - Zebra
- Colors
  - Blue
  - Green
  - Red
- Vehicles
  - Cars
    - Audi
    - BMW
    - Volkswagon
  - Planes
    - Boeing
    - Embraer
    - Airbus