• Stars
    star
    219
  • Rank 181,133 (Top 4 %)
  • Language
    JavaScript
  • Created over 9 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Element for a virtual, "infinite" list

Published on NPM Build status Published on webcomponents.org

<iron-list>

iron-list displays a virtual, 'infinite' list. The template inside the iron-list element represents the DOM to create for each list item. The items property specifies an array of list item data.

For performance reasons, not every item in the list is rendered at once; instead a small subset of actual template elements (enough to fill the viewport) are rendered and reused as the user scrolls. As such, it is important that all state of the list template be bound to the model driving it, since the view may be reused with a new model at any time. Particularly, any state that may change as the result of a user interaction with the list item must be bound to the model to avoid view state inconsistency.

Sizing iron-list

iron-list must either be explicitly sized, or delegate scrolling to an explicitly sized parent. By "explicitly sized", we mean it either has an explicit CSS height property set via a class or inline style, or else is sized by other layout means (e.g. the flex or fit classes).

Flexbox - jsbin

<style>
  :host {
    height: 100vh;
    display: flex;
    flex-direction: column;
  }

  iron-list {
    flex: 1;
  }
</style>
<app-toolbar>App name</app-toolbar>
<iron-list items="[[items]]">
  <template>
    <div>
      ...
    </div>
  </template>
</iron-list>

Explicit size - jsbin

<style>
  :host {
    display: block;
  }

  iron-list {
    height: 100vh; /* don't use % values unless the parent element is sized. */
  }
</style>
<iron-list items="[[items]]">
  <template>
    <div>
      ...
    </div>
  </template>
</iron-list>

Main document scrolling - jsbin

<head>
  <style>
    body {
      margin: 0;
    }
  </style>
</head>
<body>
  <iron-list scroll-target="document">
    <template>
      <div>
        ...
      </div>
    </template>
  </iron-list>
</body>

iron-list must be given a <template> which contains exactly one element. In the examples above we used a <div>, but you can provide any element (including custom elements).

Template model

List item templates should bind to template models of the following structure:

{
  index: 0,        // index in the item array
  selected: false, // true if the current item is selected
  tabIndex: -1,    // a dynamically generated tabIndex for focus management
  item: {}         // user data corresponding to items[index]
}

Alternatively, you can change the property name used as data index by changing the indexAs property. The as property defines the name of the variable to add to the binding scope for the array.

For example, given the following data array:

data.json
[
  {"name": "Bob"},
  {"name": "Tim"},
  {"name": "Mike"}
]

The following code would render the list (note the name property is bound from the model object provided to the template scope):

<iron-ajax url="data.json" last-response="{{data}}" auto></iron-ajax>
<iron-list items="[[data]]" as="item">
  <template>
    <div>
      Name: [[item.name]]
    </div>
  </template>
</iron-list>

Grid layout

iron-list supports a grid layout in addition to linear layout by setting the grid attribute. In this case, the list template item must have both fixed width and height (e.g. via CSS). Based on this, the number of items per row are determined automatically based on the size of the list viewport.

Accessibility

iron-list automatically manages the focus state for the items. It also provides a tabIndex property within the template scope that can be used for keyboard navigation. For example, users can press the up and down keys, as well as the left and right keys (the grid attribute is present), to move to focus between items in the list:

<iron-list items="[[data]]" as="item">
  <template>
    <div tabindex$="[[tabIndex]]">
      Name: [[item.name]]
    </div>
  </template>
</iron-list>

Styling

You can use the --iron-list-items-container mixin to style the container of items:

iron-list {
 --iron-list-items-container: {
    margin: auto;
  };
}

Resizing

iron-list lays out the items when it receives a notification via the iron-resize event. This event is fired by any element that implements IronResizableBehavior.

By default, elements such as iron-pages, paper-tabs or paper-dialog will trigger this event automatically. If you hide the list manually (e.g. you use display: none) you might want to implement IronResizableBehavior or fire this event manually right after the list became visible again. For example:

document.querySelector('iron-list').fire('iron-resize');

When should <iron-list> be used?

iron-list should be used when a page has significantly more DOM nodes than the ones visible on the screen. e.g. the page has 500 nodes, but only 20 are visible at a time. This is why we refer to it as a virtual list. In this case, a dom-repeat will still create 500 nodes which could slow down the web app, but iron-list will only create 20.

However, having an iron-list does not mean that you should load all the data at once. For example, if you have a million records in the database, it is better split the data into pages so you can bring in a page at a time. The page could contain 500 items, and iron-list might only render 20.

See: Documentation, Demo.

Usage

Installation

npm install --save @polymer/iron-list

In a Polymer 3 element

import {PolymerElement, html} from '@polymer/polymer';
import '@polymer/iron-list/iron-list.js';

class SampleElement extends PolymerElement {
  static get template() {
    return html`
      <style>
        :host {
          display: block;
        }

        iron-list {
          height: 100vh; /* don't use % values unless the parent element is sized. */
        }
      </style>
      <iron-list items="[[items]]">
        <template>
          <div>
            ...
          </div>
        </template>
      </iron-list>
    `;
  }
}
customElements.define('sample-element', SampleElement);

Contributing

If you want to send a PR to this element, here are the instructions for running the tests and demo locally:

Installation

git clone https://github.com/PolymerElements/iron-list
cd iron-list
npm install
npm install -g polymer-cli

Running the demo locally

polymer serve --npm
open http://127.0.0.1:<port>/demo/

Running the tests

polymer test --npm

More Repositories

1

app-layout

App layout elements
HTML
598
star
2

app-route

A modular client-side router
HTML
146
star
3

neon-animation

Polymer + Web Animations
JavaScript
143
star
4

paper-button

A button à la Material Design
JavaScript
138
star
5

paper-input

A Material Design text field
JavaScript
130
star
6

iron-ajax

Easily make ajax requests
HTML
127
star
7

paper-styles

Shared styles for Material Design elements
JavaScript
107
star
8

iron-icons

A set of icons for use with iron-icon
HTML
105
star
9

paper-card

A Material Design piece of paper with unique related data
JavaScript
98
star
10

paper-elements

Material design UI elements implemented using Polymer
HTML
87
star
11

iron-flex-layout

Style mixins for cross-platform flex-box layouts
HTML
85
star
12

marked-element

Element wrapper for the marked library
HTML
84
star
13

generator-polymer-init-custom-build

A Polymer CLI generator for creating custom build processes with polymer-build
JavaScript
69
star
14

platinum-sw

Service Worker Polymer element
HTML
67
star
15

paper-tabs

Material Design tabs
HTML
65
star
16

iron-form

Custom form element
HTML
63
star
17

paper-dialog

A Material Design dialog
HTML
63
star
18

app-storage

Data-pipes and specialized services
JavaScript
61
star
19

app-media

Elements for accessing data from media input devices and visualizing that data for users
JavaScript
61
star
20

paper-dropdown-menu

A Material Design browser select element
JavaScript
61
star
21

paper-checkbox

A Material Design checkbox
HTML
58
star
22

paper-ripple

Adds a Material Design ripple effect to UI elements
JavaScript
57
star
23

paper-toast

A Material Design popup toast
HTML
53
star
24

app-pouchdb

Custom Elements for working with PouchDB.
HTML
49
star
25

app-localize-behavior

Polymer behaviour to help internationalize your application
HTML
48
star
26

iron-pages

Simple content switcher
HTML
48
star
27

iron-elements

Core elements
HTML
47
star
28

paper-slider

A Material Design slider
JavaScript
47
star
29

paper-icon-button

A Material Design icon button
JavaScript
42
star
30

paper-spinner

Material Design circular activity indicator
JavaScript
41
star
31

iron-overlay-behavior

Makes an element an overlay with an optional backdrop
HTML
41
star
32

paper-tooltip

A Material Design tooltip
HTML
40
star
33

paper-toolbar

A Material Design toolbar/appbar
JavaScript
40
star
34

iron-icon

Element that displays a single icon
HTML
40
star
35

paper-swatch-picker

A color picker with all the Material Design colours
JavaScript
39
star
36

iron-image

Image element with sizing and preloading options
HTML
37
star
37

iron-iconset-svg

Represents a source of icons expressed as a collection of inline SVGs
HTML
37
star
38

iron-component-page

A reusable landing page for elements
JavaScript
36
star
39

iron-dropdown

An unstyled element that works similarly to a native browser select
HTML
34
star
40

paper-item

Material Design list items
JavaScript
33
star
41

iron-input

An input with data binding
HTML
33
star
42

paper-fab

A material design floating action button
HTML
33
star
43

iron-selector

Manages a list of elements that can be selected
HTML
32
star
44

paper-progress

A Material Design progress
JavaScript
32
star
45

paper-badge

Material Design status descriptors for elements
HTML
31
star
46

iron-collapse

Adds collapsible behavior to a target element
HTML
27
star
47

paper-toggle-button

A Material Design toggle button
JavaScript
27
star
48

iron-test-helpers

Utility classes to make testing easier
JavaScript
26
star
49

iron-a11y-announcer

An element that helps with announcing text through screen readers.
JavaScript
26
star
50

iron-meta

Element for creating and accessing self-organizing meta-databases
HTML
25
star
51

iron-media-query

Data binding for a CSS Media Query
HTML
25
star
52

paper-drawer-panel

A Material Design two-section responsive panel
JavaScript
25
star
53

iron-swipeable-container

A container that allows any of its nested children to be swiped away.
HTML
25
star
54

paper-scroll-header-panel

Fancy scrolling effects where the header animates between tall and condensed states
JavaScript
24
star
55

paper-menu-button

An element that allows composing a trigger and content as a dropdown menu.
JavaScript
24
star
56

iron-a11y-keys-behavior

A behavior that enables keybindings for greater a11y
HTML
24
star
57

paper-header-panel

A Material Design panel with top and bottom panes
JavaScript
23
star
58

iron-location

A Polymer element that manages binding to the page's URL.
HTML
22
star
59

iron-scroll-threshold

Polymer element for triggering an event when nearing the beginning or end of a scrollable element
HTML
21
star
60

test-fixture

JavaScript
21
star
61

paper-listbox

HTML
21
star
62

paper-behaviors

Common behaviors used across paper-* elements.
HTML
19
star
63

paper-radio-button

A Material Design radio button
HTML
19
star
64

iron-autogrow-textarea

Textarea that grows in height as more lines of input are entered
JavaScript
19
star
65

iron-a11y-keys

A basic element implementation of iron-a11y-keys-behavior
JavaScript
19
star
66

paper-material

A Material Design container that looks like a lifted piece of paper
HTML
19
star
67

paper-radio-group

A group of Material Design radio buttons
HTML
19
star
68

iron-menu-behavior

Accessible menu behavior
HTML
18
star
69

paper-dialog-behavior

Makes an element a Material Design dialog
HTML
18
star
70

prism-element

Prism-based syntax highlighting
JavaScript
17
star
71

iron-fit-behavior

Fits an element into another element
HTML
17
star
72

gold-email-input

An input element that only allows emails
HTML
17
star
73

iron-doc-viewer

Polymer documentation viewer elements
JavaScript
17
star
74

font-roboto-local

JavaScript
16
star
75

iron-demo-helpers

Utility classes to make building demo pages easier
JavaScript
16
star
76

paper-dialog-scrollable

A scrollable area used in a Material Design dialog
HTML
15
star
77

iron-resizable-behavior

HTML
14
star
78

iron-jsonp-library

Loads jsonp libraries.
JavaScript
14
star
79

iron-behaviors

Behaviors that manage control states like 'focused', 'disabled', and 'active'
HTML
14
star
80

iron-iconset

Represents a source of icons expressed as a raster sprite sheet
JavaScript
13
star
81

gold-phone-input

An input element that only allows phone numbers
HTML
13
star
82

gold-cc-input

An input element that only allows credit card numbers
JavaScript
13
star
83

iron-localstorage

Access to localStorage
HTML
11
star
84

iron-validator-behavior

Implements a custom input or form validator
HTML
11
star
85

gold-elements

Business elements
9
star
86

neon-elements

Elements that implement special effects
9
star
87

iron-form-element-behavior

Behavior that enables an element to be included in an iron-form
JavaScript
9
star
88

iron-scroll-target-behavior

Polymer behavior that allows to define a scroller target
HTML
8
star
89

iron-range-behavior

Managing a numeric value within a given range
HTML
8
star
90

gold-cc-cvc-input

An input element that only allows cvc codes
HTML
8
star
91

iron-validatable-behavior

Implements an element validated with Polymer.IronValidatorBehavior
JavaScript
7
star
92

iron-label

A version of the <label> element that works with Custom Elements as well as native elements.
HTML
7
star
93

gold-cc-expiration-input

An input element that only allows credit card expiration dates
JavaScript
6
star
94

iron-checked-element-behavior

Implements an element that has a checked attribute and can be added to a form
HTML
5
star
95

app-elements

Application level elements
HTML
5
star
96

font-roboto

Loads the Roboto family of fonts from Google Fonts.
JavaScript
5
star
97

gold-zip-input

An input element that only allows US zip codes
JavaScript
5
star
98

platinum-elements

push notifications, offline usage, bluetooth and more.
4
star
99

paper-ui-elements

A collection of Material Design UI components
2
star
100

ContributionGuide

Canonical repo for the Polymer Elements contribution guide.
1
star