list docs

2.14.0

List

List Component in Bolt

Published

History
View changes
Install
yarn add @bolt/components-list
Source code
View on Github
Dependencies

Overview

Minimal list component for laying out a group of items. Part of the Bolt “Components” CSS framework that powers the Bolt Design System.

Install via NPM
npm install @bolt/components-list

Usage

  {% include "@bolt-components-list/list.twig" with {
  display: "inline",
  spacing: "xsmall",
  align: "start",
  valign: "center",
  items: [
    "Item 1",
    "Item 2",
    "Item 3",
    "Item 4",
    "Item 5",
  ]
} only %}

Schema

Note: when assigning component props as HTML attributes on a web component, make sure to use kebab-case.

Prop Name Description Type Default Value Option(s)
Attributes

A Drupal-style attributes object with extra attributes to append to this component.

 object —
  • —
Items *

Generates an array of items, each can contain renderable content (i.e. a string, render array, or included pattern).

 array —
  • —
Tag

Apply the semantic tag for the list.

 string ul
  • ul, ol, div, span
Display

Display either an inline list of items or a block (stacked) list of items. Responsive options are also available for transforming from block to inline at specific breakpoints.

 string block
  • block, flex, inline, inline@xxsmall, inline@xsmall, inline@small, inline@medium
Spacing

Control the spacing in between items.

 string xsmall
  • none, xxsmall, xsmall, small, medium, large, xlarge
Separator

Display a separator in between items.

 string none
  • none, solid, dashed
Inset

Turn spacing to the inside of each item.

 boolean false
  • true or false
Align

Control the horizontal alignment of items.

 string start
  • start, center, end, justify
Valign

Control the vertical alignment of items.

 string center
  • start, center, end
Nowrap

Prevent inline/flex list items from wrapping to a second line.

 boolean false
  • true or false

list

  • Item 1
  • Item 2
  • Item 3

list item variations

Inline list of different items

Inline list of chips

Inline list of buttons

list display variations

Block

  • Item 1
  • Item 2
  • Item 3

Flex

  • Item 1
  • Item 2
  • Item 3

Inline

  • Item 1
  • Item 2
  • Item 3

Inline@xxsmall

  • Item 1
  • Item 2
  • Item 3

Inline@xsmall

  • Item 1
  • Item 2
  • Item 3

Inline@small

  • Item 1
  • Item 2
  • Item 3

Inline@medium

  • Item 1
  • Item 2
  • Item 3

Inline@breakpoint

Note: this type of display option will transform a block list to inline when the browser is equal to or greater than the breakpoint specified.

list spacing variations

Block list with spacing (none)

  • Item 1
  • Item 2
  • Item 3

Block list with spacing (xxsmall)

  • Item 1
  • Item 2
  • Item 3

Block list with spacing (xsmall)

  • Item 1
  • Item 2
  • Item 3

Block list with spacing (small)

  • Item 1
  • Item 2
  • Item 3

Block list with spacing (medium)

  • Item 1
  • Item 2
  • Item 3

Block list with spacing (large)

  • Item 1
  • Item 2
  • Item 3

Block list with spacing (xlarge)

  • Item 1
  • Item 2
  • Item 3

Flex list with spacing (none)

  • Item 1
  • Item 2
  • Item 3

Flex list with spacing (xxsmall)

  • Item 1
  • Item 2
  • Item 3

Flex list with spacing (xsmall)

  • Item 1
  • Item 2
  • Item 3

Flex list with spacing (small)

  • Item 1
  • Item 2
  • Item 3

Flex list with spacing (medium)

  • Item 1
  • Item 2
  • Item 3

Flex list with spacing (large)

  • Item 1
  • Item 2
  • Item 3

Flex list with spacing (xlarge)

  • Item 1
  • Item 2
  • Item 3

Inline list with spacing (none)

  • Item 1
  • Item 2
  • Item 3

Inline list with spacing (xxsmall)

  • Item 1
  • Item 2
  • Item 3

Inline list with spacing (xsmall)

  • Item 1
  • Item 2
  • Item 3

Inline list with spacing (small)

  • Item 1
  • Item 2
  • Item 3

Inline list with spacing (medium)

  • Item 1
  • Item 2
  • Item 3

Inline list with spacing (large)

  • Item 1
  • Item 2
  • Item 3

Inline list with spacing (xlarge)

  • Item 1
  • Item 2
  • Item 3

list separator variations

Solid separators in a block list

  • Item 1
  • Item 2
  • Item 3

Solid separators in a flex list

  • Item 1
  • Item 2
  • Item 3

Solid separators in a inline list

  • Item 1
  • Item 2
  • Item 3

Dashed separators in a block list

  • Item 1
  • Item 2
  • Item 3

Dashed separators in a flex list

  • Item 1
  • Item 2
  • Item 3

Dashed separators in a inline list

  • Item 1
  • Item 2
  • Item 3

list inset variations

Regular spacing in a block list

  • Item 1
  • Item 2
  • Item 3

Inset spacing in a block list

  • Item 1
  • Item 2
  • Item 3

Regular spacing in a inline list

  • Item 1
  • Item 2
  • Item 3

Inset spacing in a inline list

  • Item 1
  • Item 2
  • Item 3

Regular spacing in a flex list

  • Item 1
  • Item 2
  • Item 3

Inset spacing in a flex list

  • Item 1
  • Item 2
  • Item 3

list regular vs inset spacing

Regular vs inset spacing

There are 2 different types of spacing styles and you can use it to your advantage. Different layouts call for different spacing styles, use your best judgment to apply the more applicable style.

The advantage of using regular spacing style

This is the regular spacing style, which adds space only in between items. So when it is put side by side next to a paragraph of text, the top of the list will line up with the paragraph of text (optically). Phasellus molestie magna non est bibendum non venenatis nisl tempor. Suspendisse dictum feugiat nisl ut dapibus. Mauris iaculis porttitor posuere. Praesent id metus massa, ut blandit odio. Proin quis tortor orci. Etiam at risus et justo dignissim congue. Donec congue lacinia dui, a porttitor lectus condimentum laoreet. Nunc eu ullamcorper orci. Quisque eget odio ac lectus vestibulum faucibus eget in metus. Vivamus hendrerit arcu sed erat molestie vehicula. Sed auctor neque eu tellus rhoncus ut eleifend nibh porttitor. Ut in nulla enim. Phasellus molestie magna non est bibendum non venenatis nisl tempor. Suspendisse dictum feugiat nisl ut dapibus. Mauris iaculis porttitor posuere. Praesent id metus massa, ut blandit odio. Proin quis tortor orci. Etiam at risus et justo dignissim congue. Donec congue lacinia dui, a porttitor lectus condimentum laoreet. Nunc eu ullamcorper orci. Quisque eget odio ac lectus vestibulum faucibus eget in metus. In pellentesque faucibus vestibulum. Nulla at nulla justo, eget luctus tortor. Nulla facilisi. Duis aliquet egestas purus in blandit. Curabitur vulputate, ligula lacinia scelerisque tempor, lacus lacus ornare ante, ac egestas est urna sit amet arcu. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Sed molestie augue sit amet leo consequat posuere. Vestibulum ante.

The same applies to items with a background color. Phasellus molestie magna non est bibendum non venenatis nisl tempor. Suspendisse dictum feugiat nisl ut dapibus. Mauris iaculis porttitor posuere. Praesent id metus massa, ut blandit odio. Proin quis tortor orci. Etiam at risus et justo dignissim congue. Donec congue lacinia dui, a porttitor lectus condimentum laoreet. Nunc eu ullamcorper orci. Quisque eget odio ac lectus vestibulum faucibus eget in metus. Vivamus hendrerit arcu sed erat molestie vehicula. Sed auctor neque eu tellus rhoncus ut eleifend nibh porttitor. Ut in nulla enim. Phasellus molestie magna non est bibendum non venenatis nisl tempor. Suspendisse dictum feugiat nisl ut dapibus. Mauris iaculis porttitor posuere. Praesent id metus massa, ut blandit odio. Proin quis tortor orci. Etiam at risus et justo dignissim congue. Donec congue lacinia dui, a porttitor lectus condimentum laoreet. Nunc eu ullamcorper orci. Quisque eget odio ac lectus vestibulum faucibus eget in metus. In pellentesque faucibus vestibulum. Nulla at nulla justo, eget luctus tortor. Nulla facilisi. Duis aliquet egestas purus in blandit. Curabitur vulputate, ligula lacinia scelerisque tempor, lacus lacus ornare ante, ac egestas est urna sit amet arcu. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Sed molestie augue sit amet leo consequat posuere. Vestibulum ante.

  • Item 1
  • Item 2
  • Item 3

The advantage of using inset spacing style

Inset spacing puts spacing around each item, this is very useful if you are putting the list inside any kind of box container. Phasellus molestie magna non est bibendum non venenatis nisl tempor. Suspendisse dictum feugiat nisl ut dapibus. Mauris iaculis porttitor posuere. Praesent id metus massa, ut blandit odio. Proin quis tortor orci. Etiam at risus et justo dignissim congue. Donec congue lacinia dui, a porttitor lectus condimentum laoreet. Nunc eu ullamcorper orci. Quisque eget odio ac lectus vestibulum faucibus eget in metus. Vivamus hendrerit arcu sed erat molestie vehicula. Sed auctor neque eu tellus rhoncus ut eleifend nibh porttitor. Ut in nulla enim. Phasellus molestie magna non est bibendum non venenatis nisl tempor. Suspendisse dictum feugiat nisl ut dapibus. Mauris iaculis porttitor posuere. Praesent id metus massa, ut blandit odio. Proin quis tortor orci. Etiam at risus et justo dignissim congue. Donec congue lacinia dui, a porttitor lectus condimentum laoreet. Nunc eu ullamcorper orci. Quisque eget odio ac lectus vestibulum faucibus eget in metus. In pellentesque faucibus vestibulum. Nulla at nulla justo, eget luctus tortor. Nulla facilisi. Duis aliquet egestas purus in blandit. Curabitur vulputate, ligula lacinia scelerisque tempor, lacus lacus ornare ante, ac egestas est urna sit amet arcu. Class aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos himenaeos. Sed molestie augue sit amet leo consequat posuere. Vestibulum ante.

  • Item 1
  • Item 2
  • Item 3

^ This list is inside a colored box.

list align variations

Align prop only works with inline display, it has no effects on block and flex display.

Horizontally align inline items: start

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@xxsmall items: start

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@xsmall items: start

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@small items: start

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@medium items: start

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline items: center

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@xxsmall items: center

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@xsmall items: center

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@small items: center

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@medium items: center

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline items: end

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@xxsmall items: end

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@xsmall items: end

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@small items: end

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@medium items: end

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline items: justify

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@xxsmall items: justify

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@xsmall items: justify

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@small items: justify

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline@medium items: justify

  • Item 1
  • Item 2
  • Item 3

list valign variations

Valign prop only works with inline and flex display, it has no effects on block display.

Vertically align inline items: start

  • Item 1
  • Item 2
  • Item 3

Vertically align inline items: center

  • Item 1
  • Item 2
  • Item 3

Vertically align inline items: end

  • Item 1
  • Item 2
  • Item 3

Vertically align flex items: start

  • Item 1
  • Item 2
  • Item 3

Vertically align flex items: center

  • Item 1
  • Item 2
  • Item 3

Vertically align flex items: end

  • Item 1
  • Item 2
  • Item 3

list tag variations

Use the semantically correct tag based on the context of your page layout.

ul

ol

  1. Item 1
  2. Item 2
  3. Item 3

div

Item 1 Item 2 Item 3

span

Item 1 Item 2 Item 3

list nowrap variations

Nowrap prop only works with inline and flex display, it has no effects on block display.

Inline list with nowrap

  • Item 1
  • Item 2
  • Item 3
  • Item 4
  • Item 5
  • Item 6

Flex list with nowrap

  • Item 1
  • Item 2
  • Item 3
  • Item 4
  • Item 5
  • Item 6

list with web component

Web Component Usage Bolt Button is a web component, you can simply use <bolt-list> in the markup to make it render.
Item 1 Item 2 Item 3
<bolt-list> <bolt-list-item>Item 1</bolt-list-item> <bolt-list-item>Item 2</bolt-list-item> <bolt-list-item>Item 3</bolt-list-item> </bolt-list>
Basic Usage All the props defined in the schema table can be used directly on the <bolt-list> element.
Item 1 Item 2 Item 3
<bolt-list display="inline" spacing="xsmall" separator="dashed" align="center" > <bolt-list-item>Item 1</bolt-list-item> <bolt-list-item>Item 2</bolt-list-item> <bolt-list-item>Item 3</bolt-list-item> </bolt-list>
Advanced Usage Instead of passing plain text into each item, you may also pass other Bolt components or regular HTML.
Item 1 Item 2 Item 3
<bolt-list display="inline"> <bolt-list-item> <bolt-link url="https://pega.com"> Item 1 </bolt-link> </bolt-list-item> <bolt-list-item> <bolt-chip url="https://pega.com"> Item 2 </bolt-chip> </bolt-list-item> <bolt-list-item> <bolt-button url="https://pega.com"> Item 3 </bolt-button> </bolt-list-item> </bolt-list>
Debug Panel