Lists

The List Row component helps group overview information. The information presented should be scannable and actionable.

This component handles a lot of the accessibility support for you. However, there are a handful of things you must add on a per-usage basis to ensure full support. Most importantly, you need to add role="cell" to cells within the row-body slot. For more details, see the accessibility section at the end of these docs.

List Row: how to use

1 2 3 4 5 6 7 8 9 10 11
1
2
3
4
5
6
7
8
 Body Body Body Body Body Body Body Body Actions
1
2
3
4
5
6
7
8
 Select Row Body Body Body Body Body Body Body Body
1
2
3
4
5
6
7
8
 
<tk-list class="demo" caption="List Row Example">
  <tk-list-columns class="mb-3x" sort-enabled>
    <tk-list-column>1</tk-list-column>
    <tk-list-column>2</tk-list-column>
    <tk-list-column>3</tk-list-column>
    <tk-list-column>4</tk-list-column>
    <tk-list-column>5</tk-list-column>
    <tk-list-column>6</tk-list-column>
    <tk-list-column>7</tk-list-column>
    <tk-list-column>8</tk-list-column>
    <tk-list-column>9</tk-list-column>
    <tk-list-column>10</tk-list-column>
    <tk-list-column>11</tk-list-column>
  </tk-list-columns>

  <tk-list-row>
    <tk-row-selector slot="row-selector" size="medium"></tk-row-selector>
    <tk-icon class="demo-pre" slot="row-icon" name="idea" size="large" muted></tk-icon>
    <div class="demo-body" slot="row-body">
      <div role="cell">1</div>
      <div role="cell">2</div>
      <div role="cell">3</div>
      <div role="cell">4</div>
      <div role="cell">5</div>
      <div role="cell">6</div>
      <div role="cell">7</div>
      <div role="cell">8</div>
    </div>
    <tk-dropdown class="demo-actions" slot="row-actions" trigger-type="action">
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Add Elixir</button>
      </tk-dropdown-item>
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Add Potion</button>
      </tk-dropdown-item>
    </tk-dropdown>
  </tk-list-row>
</tk-list>

<tk-list class="demo" caption="List Row Example #2">
  <tk-list-columns class="mb-3x" sort-enabled>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Actions</tk-list-column>
  </tk-list-columns>

  <tk-list-row>
    <div class="demo-body" slot="row-body">
      <div role="cell">1</div>
      <div role="cell">2</div>
      <div role="cell">3</div>
      <div role="cell">4</div>
      <div role="cell">5</div>
      <div role="cell">6</div>
      <div role="cell">7</div>
      <div role="cell">8</div>
    </div>
    <tk-dropdown class="demo-actions" slot="row-actions" trigger-type="action">
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Add Elixir</button>
      </tk-dropdown-item>
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Add Potion</button>
      </tk-dropdown-item>
    </tk-dropdown>
  </tk-list-row>
</tk-list>

<tk-list class="demo" caption="List Row Example #3">
  <tk-list-columns class="mb-3x">
    <tk-list-column sr-only>Select Row</tk-list-column>
    <tk-list-column start="2">Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
  </tk-list-columns>

   <tk-list-row>
    <tk-row-selector slot="row-selector" size="medium"></tk-row-selector>
    <div class="demo-body" slot="row-body">
      <div role="cell">1</div>
      <div role="cell">2</div>
      <div role="cell">3</div>
      <div role="cell">4</div>
      <div role="cell">5</div>
      <div role="cell">6</div>
      <div role="cell">7</div>
      <div role="cell">8</div>
    </div>
  </tk-list-row>
</tk-list>

Description

The List Row component has four areas for content: row-selector, row-icon, row-body, and row-actions.

Row Selector (optional)

The row-selector will always appear as the first element in the row. It should be used for bulk actions.

Row Icon (optional)

The row-icon will always appear as the second element in the row.

Row Body

The row-body holds the main content of the List Row. For every table cell, you need to add role="cell".

Row Actions (optional)

The row-actions will always appear last in the row. Most likely, you’ll want to use our tk-dropdown here.

Column Headers (optional)

Column headers are useful for giving the user context about the List Row content. If using tk-list-columns, the next element sibling must be tk-list-row, and its descendants must be the slotted areas. Any wrappers between these elements will mess up the grid alignment of the headers.

List Row: start and span

Row Icon span 2, start 2 Body Body span 3 Body Actions
span="2"
3
4
span="3"
8
 Row Icon span 2, start 4 span 2 span 1 start 9
start="3" span="2"
span="2"
7
8
 span 4 span 3 8 Actions
span="4"
span="3"
8
 
<tk-list class="demo" caption="Start and Span Example #1">
  <tk-list-columns class="mb-3x">
    <tk-list-column sr-only>Row Icon</tk-list-column>
    <tk-list-column span="2" start="2">span 2, start 2</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column span="3">span 3</tk-list-column>
    <tk-list-column>Body</tk-list-column>
    <tk-list-column>Actions</tk-list-column>
  </tk-list-columns>

   <tk-list-row>
    <tk-icon class="demo-pre" slot="row-icon" name="idea" size="large" muted></tk-icon>
    <div class="demo-body" slot="row-body">
      <div span="2" role="cell">span="2"</div>
      <div role="cell">3</div>
      <div role="cell">4</div>
      <div span="3" role="cell">span="3"</div>
      <div role="cell">8</div>
    </div>
    <tk-dropdown class="demo-actions" slot="row-actions" trigger-type="action">
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Button</button>
      </tk-dropdown-item>
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Button #2</button>
      </tk-dropdown-item>
    </tk-dropdown>
  </tk-list-row>
</tk-list>

<tk-list class="demo" caption="Start and Span Example #2">
  <tk-list-columns class="mb-3x">
    <tk-list-column sr-only>Row Icon</tk-list-column>
    <tk-list-column span="2" start="4">span 2, start 4</tk-list-column>
    <tk-list-column span="2">span 2</tk-list-column>
    <tk-list-column sr-only>span 1</tk-list-column>
    <tk-list-column start="9">start 9</tk-list-column>
  </tk-list-columns>

   <tk-list-row>
    <tk-icon class="demo-pre" slot="row-icon" name="idea" size="large" muted></tk-icon>
    <div class="demo-body" slot="row-body">
      <div role="cell" start="3" span="2">start="3" span="2"</div>
      <div role="cell" span="2">span="2"</div>
      <div role="cell">7</div>
      <div role="cell">8</div>
    </div>
  </tk-list-row>
</tk-list>

<tk-list class="demo" caption="Start and Span Example #3">
  <tk-list-columns class="mb-3x">
    <tk-list-column span="4">span 4</tk-list-column>
    <tk-list-column span="3">span 3</tk-list-column>
    <tk-list-column>8</tk-list-column>
    <tk-list-column>Actions</tk-list-column>
  </tk-list-columns>

   <tk-list-row>
    <div class="demo-body" slot="row-body">
      <div role="cell" span="4">span="4"</div>
      <div role="cell" span="3">span="3"</div>
      <div role="cell">8</div>
    </div>
    <tk-dropdown class="demo-actions" slot="row-actions" trigger-type="action">
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Add Elixir</button>
      </tk-dropdown-item>
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Add Potion</button>
      </tk-dropdown-item>
    </tk-dropdown>
  </tk-list-row>
</tk-list>

Description

Row Body

The row-body can be split into 8 columns. The default for each element is to span 1 column. To control how many columns an element spans, use span="x". To offset an element, add start="x".

Column Headers

Column headers can also accept span and start. Start is dependent on how many items are in the row: 8 for row-body, 1 for row-selector, 1 for row-icon, and 1 for row-actions. This means there’s a max of 11.

List Row: custom columns

icon 1 1 3 1 span 3 4 actions
1
1
3
1 span 3
4
 
<tk-list class="demo" caption="Custom Columns">
  <tk-list-columns class="mb-3x" id="custom-columns">
    <tk-list-column>icon</tk-list-column>
    <tk-list-column>1</tk-list-column>
    <tk-list-column>1</tk-list-column>
    <tk-list-column>3</tk-list-column>
    <tk-list-column span="3">1 span 3</tk-list-column>
    <tk-list-column>4</tk-list-column>
    <tk-list-column>actions</tk-list-column>
  </tk-list-columns>

   <tk-list-row id="custom-columns-row">
    <tk-icon class="demo-pre" slot="row-icon" name="idea" size="large" muted></tk-icon>
    <div class="demo-body" slot="row-body">
      <div role="cell">1</div>
      <div role="cell">1</div>
      <div role="cell">3</div>
      <div role="cell" span="3">1 span 3</div>
      <div role="cell">4</div>
    </div>
    <tk-dropdown class="demo-actions" slot="row-actions" trigger-type="action">
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Button</button>
      </tk-dropdown-item>
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Button #2</button>
      </tk-dropdown-item>
    </tk-dropdown>
  </tk-list-row>
</tk-list>

<!-- only required for use outside of a framework -->
<script>
  const columnWidths = [1, 1, 3, 1, 1, 1, 4];
  document.getElementById('custom-columns').columnWidths = columnWidths;
  document.getElementById('custom-columns-row').columnWidths = columnWidths;
</script>

Description

Row Body

The row-body can have a custom number of columns with custom width. The default is 8 columns. To control how many columns and their sizes, use the column-widths prop.

Column Headers

Column headers can also accept column-widths. The default is also 8 columns.

Column Sort

First Second Third
The first column.
The second column.
The third column.

Click a column title to see the output.

<tk-list caption="Column Examples">
  <tk-list-columns id="sortExample" sort-enabled>
    <tk-list-column span="3">First</tk-list-column>
    <tk-list-column span="3">Second</tk-list-column>
    <tk-list-column>Third</tk-list-column>
  </tk-list-columns>

  <tk-list-row class="mt-2x">
    <div slot="row-body">
      <div role="cell" span="3">The first column.</div>
      <div role="cell" span="3">The second column.</div>
      <div role="cell" span="2">The third column.</div>
    </div>
  </tk-list-row>
</tk-list>

<p id="sortExampleText">Click a column title to see the output.</p>
<script>
  const exampleText = document.getElementById('sortExampleText');
  const columns = Array.from(document.getElementById('sortExample').children);
  columns.forEach((column, i) => {
    column.addEventListener('sortSelected', ev => {
      exampleText.innerText = `Column ${i + 1}, Sort: ${ev.detail.sort}`;
    });
  })
</script>

Description

When sort is enabled (sort-enabled), the column headers are buttons that emit an event (sortSelected) when clicked. The event emits the direction (event.detail.sort) that provides if it’s ASC or DESC.

Setting initial sort

To set a column as the initial sort, set the attribute sort="asc" or sort="desc" on tk-list-column. If an initial sort is not provided, the component will default to the first tk-list-column being sort="asc".

Angular example

<tk-list-column (sortEnabled)="myMethod($event)">Column 2</tk-list-column>

Flush rows, Light headers

Type Subject Review Start Date

Most wizards found this course to be difficult.

May 28, 1993

Most wizards found this course to be enjoyable.

May 27, 1993

 
<tk-list flush caption="Available Courses">
  <tk-list-columns class="mb-3x" light>
    <tk-list-column>Type</tk-list-column>
    <tk-list-column span="3">Subject</tk-list-column>
    <tk-list-column start="6" span="3">Review</tk-list-column>
    <tk-list-column>Start Date</tk-list-column>
  </tk-list-columns>

   <tk-list-row>
    <tk-icon slot="row-icon" name="idea" size="large" muted></tk-icon>
    <div slot="row-body">
      <div role="cell" span="3">
        <h2><a class="row-title" href="#">COURSE 3500: Study of Ancient Runes</a></h2>
        <p class="t-small">N.E.W.T. requirement</p>
      </div>
      <p role="cell" start="5" span="3">Most wizards found this course to be <strong>difficult</strong>.</p>
      <p>May 28, 1993</p>
    </div>
  </tk-list-row>
  <tk-list-row>
    <tk-icon slot="row-icon" name="idea" size="large" muted></tk-icon>
    <div slot="row-body">
      <div role="cell" span="3">
        <h2><a class="row-title" href="#">COURSE 3300: Care of Magical Creatures</a></h2>
        <p class="t-small">N.E.W.T. requirement</p>
      </div>
      <p role="cell" start="5" span="3">Most wizards found this course to be <strong>enjoyable</strong>.</p>
      <p role="cell">May 27, 1993</p>
    </div>
  </tk-list-row>
</tk-list>

Description

To remove the margin between the List Rows, add flush to tk-list. To use inverse the colors of the column headers, add light to tk-list-columns.

List Row: example

Select Course Type Subject Status Instructor Start Date Course Actions
Enrolled

Prof. Hagrid

May 27, 1993

 
<tk-list caption="Available Courses">
  <tk-list-columns class="mb-3x">
    <tk-list-column sr-only>Select Course</tk-list-column>
    <tk-list-column start="2">Type</tk-list-column>
    <tk-list-column span="5">Subject</tk-list-column>
    <tk-list-column>Status</tk-list-column>
    <tk-list-column>Instructor</tk-list-column>
    <tk-list-column>Start Date</tk-list-column>
    <tk-list-column sr-only>Course Actions</tk-list-column>
  </tk-list-columns>

  <tk-list-row>
    <tk-row-selector slot="row-selector" size="medium"></tk-row-selector>
    <tk-icon class="sm-hide" slot="row-icon" name="usability" muted size="large"></tk-icon>
    <div slot="row-body">
      <div role="cell" span="5">
        <h2><a class="row-title" href="#">COURSE 3300: Care of Magical Creatures</a></h2>
        <p class="row-subtitle" role="cell">N.E.W.T. requirement</p>
      </div>
      <tk-indicator role="cell" type="approved">Enrolled</tk-indicator>
      <p role="cell">Prof. Hagrid</p>
      <p role="cell">May 27, 1993</p>
    </div>
    <tk-dropdown slot="row-actions" trigger-type="action">
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Drop Course</button>
      </tk-dropdown-item>
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Email Professor</button>
      </tk-dropdown-item>
    </tk-dropdown>
  </tk-list-row>
</tk-list>

Description

The List Row component listens for the select event to fire. It then updates with the appropriate styles and aria attributes.

List Row + Header

Available Subjects

Enrollment approval is at the Professor's discretion and will be allotted to students considered to be in good standing.

Care of Magical Creatures

Learn how to properly care for the wizarding world's most enchanting creatures with a world-renowned expert. In this course you'll gain experience with flobberworms, dragons, hippogriffs, nifflers…and so many more.

 
<tk-list flush caption="Available Subjects">
  <tk-list-header>
    <h2 slot="title">Available Subjects</h2>
    <p slot="subtitle">Enrollment approval is at the Professor's discretion and will be allotted to students considered to be in good standing.</p>
    <button class="btn t-link ml-auto" type="button">Contact</button>
  </tk-list-header>

  <tk-list-row>
    <tk-stamp slot="row-icon" icon="info--filled"></tk-stamp>
    <div slot="row-body">
      <div role="cell" span="8">
        <h2>Care of Magical Creatures</h2>
        <p>Learn how to properly care for the wizarding world's most enchanting creatures with a world-renowned expert. In this course you'll gain experience with flobberworms, dragons, hippogriffs, nifflers…and so many more.</p>
      </div>
    </div>
  </tk-list-row>
</tk-list>

Description

The List Row component listens for the select event to fire. It then updates with the appropriate styles and aria attributes.

List Row Status

Select Course Type Course Name Enrollment Status Professor Name Enrollment Date Course Actions
Dropped

Prof. Trelawney

May 27, 1993
Enrolled

Prof. Hagrid

May 27, 1994
Waitlist

Prof. Lupin

May 27, 1995

 
<tk-list caption="My Hogwarts Courses">
  <tk-list-columns>
    <tk-list-column sr-only>Select Course</tk-list-column>
    <tk-list-column sr-only>Type</tk-list-column>
    <tk-list-column sr-only>Course Name</tk-list-column>
    <tk-list-column sr-only>Enrollment Status</tk-list-column>
    <tk-list-column sr-only>Professor Name</tk-list-column>
    <tk-list-column sr-only>Enrollment Date</tk-list-column>
    <tk-list-column sr-only>Course Actions</tk-list-column>
  </tk-list-columns>
  <tk-list-row status="error">
    <tk-row-selector slot="row-selector" size="medium"></tk-row-selector>
    <tk-icon class="sm-hide" slot="row-icon" name="clip" muted size="large"></tk-icon>
    <div slot="row-body">
      <div role="cell" span="5">
        <h2><a class="row-title" href="#">COURSE 3400: Divination</a></h2>
      </div>
      <tk-indicator role="cell" type="error">Dropped</tk-indicator>
      <p role="cell">Prof. Trelawney</p>
      <p role="cell">May 27, 1993</p>
    </div>
    <tk-dropdown slot="row-actions" trigger-type="action">
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Join Course</button>
      </tk-dropdown-item>
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Email Professor</button>
      </tk-dropdown-item>
    </tk-dropdown>
  </tk-list-row>
  <tk-list-row status="success">
    <tk-row-selector slot="row-selector" size="medium"></tk-row-selector>
    <tk-icon class="sm-hide" slot="row-icon" name="bolt" muted size="large"></tk-icon>
    <div slot="row-body">
      <div role="cell" span="5">
        <h2><a class="row-title" href="#">COURSE 3300: Care of Magical Creatures</a></h2>
        <p class="row-subtitle">N.E.W.T. requirement</p>
      </div>
      <tk-indicator role="cell" type="approved">Enrolled</tk-indicator>
      <p role="cell">Prof. Hagrid</p>
      <p role="cell">May 27, 1994</p>
    </div>
    <tk-dropdown slot="row-actions" trigger-type="action">
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Drop Course</button>
      </tk-dropdown-item>
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Email Professor</button>
      </tk-dropdown-item>
    </tk-dropdown>
  </tk-list-row>
  <tk-list-row status="pending">
    <tk-row-selector slot="row-selector" size="medium"></tk-row-selector>
    <tk-icon class="sm-hide" slot="row-icon" name="quick-test" muted size="large"></tk-icon>
    <div slot="row-body">
      <div role="cell" span="5">
        <h2><a class="row-title" href="#">COURSE 3500: Defence Against the Dark Arts</a></h2>
        <p class="row-subtitle">N.E.W.T. requirement</p>
      </div>
      <tk-indicator role="cell" type="pending">Waitlist</tk-indicator>
      <p role="cell">Prof. Lupin</p>
      <p role="cell">May 27, 1995</p>
    </div>
    <tk-dropdown slot="row-actions" trigger-type="action">
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Drop Course</button>
      </tk-dropdown-item>
      <tk-dropdown-item>
        <button class="dropdown__link" type="button">Email Professor</button>
      </tk-dropdown-item>
    </tk-dropdown>
  </tk-list-row>
</tk-list>

Description

This pattern can be found on the main dashboard. To output rows that have a status, add status to tk-list-row. Note that the columns are still provided for assistive technology, even though they are visually hidden.

Accessibility

  • Add the caption Prop to tk-list to describe the table to screen readers.
  • role="cell" must be added to each of the corresponding table cells inside row-body. It is automatically added for the other sections (row-selector, row-actions, row-icon). This is needed because the component cannot determine which HTML elements are cells and what column it corresponds to. For example, a cell could be nested several layers in the row-body, or it could be the first child element.
  • The number of column headers must match the number of cells. If you need to visually hide the column header, then add the sr-only Prop to it.

Props: tk-list

Property Type Default Description
flush boolean false Removes margin and adds border between tk-list-row elements.
caption string Summary text provided to screen readers that describes the table.

Props: tk-list-row

Property Type Default Description
status string success pending error Adds a status border to the List Row.
compact boolean false Decreases the padding of the List Row.
isSelected boolean true Selection state of the List Row.
column-widths number[] [1, 1, 1, 1, 1, 1, 1, 1] Set the column width ratios for the row cells.

Props: tk-list-header

Property Type Default Description
compact boolean false Decreases the padding of the List Header.

Props: tk-list-columns

Property Type Default Description
light boolean false Sets the List Column text to light.
sort-enabled boolean false Sets whether sort should apply to the columns. Our UX states that it should be applied to all columns for a consistent experience.
show-columns boolean true Hides the columns. Once enabled, it recalculates the column width based on tk-list-row. Useful if tk-list-row takes longer than expected to load.
column-widths number[] [1, 1, 1, 1, 1, 1, 1, 1] Set the column width ratios for the column headers.

Props: tk-list-column

Property Type Default Description
sort `ASC DESC` -
srOnly boolean false Sets the column to screen-reader only, so that it is visually hidden.

Events

Name Description
sortSelected Emits the direction (event.detail.sort) and provides if it’s ASC or DESC.

Usage

Do

  • Ensure the actions are clearly visible

Don't

  • Use light columns on a light background
  • Nest List Rows within each other

Typography lists such as bulleted and numbered can be found in the Typography section.