list docs

List

Minimal layout container for displaying a group of items.

Published Last updated: 4.4.0 Change log Github NPM
Twig 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
  • —
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
  • —
Install Install 
npm install @bolt/components-list
Dependencies @bolt/core-v3.x @bolt/lazy-queue wc-context

list

Item 1
Item 2
Item 3

list item variations

Inline list of different items

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

Inline list of chips

Item 1 Item 2 Item 3

Inline list of buttons

Item 1 Item 2 Item 3

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.

Item 1 Item 2 Item 3

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

Item 1 Item 2 Item 3

ol

Item 1 Item 2 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>
    <a href="https://pega.com" class="e-bolt-text-link">
      Item 1
    </a>
  </bolt-list-item>
  <bolt-list-item>
    <bolt-chip url="https://pega.com">
      Item 2
    </bolt-chip>
  </bolt-list-item>
  <bolt-list-item>
    <a href="https://pega.com" class="e-bolt-button">
      Item 3
    </a>
  </bolt-list-item>
</bolt-list>