list docs

2.5.1

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",
    include("@bolt-components-link/link.twig", {
      text: "Item 2",
      url: "#!",
    }),
    include("@bolt-components-chip/chip.twig", {
      text: "Item 3",
      url: "#!",
    }),
    include("@bolt-components-button/button.twig", {
      text: "Item 4",
      url: "#!",
      size: "small",
    }),
    "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 *

All items can be simple text or items.

 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
valign

Control the vertical alignment of items.

 string center
  • start, center, end

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

Flex list with spacing (none)

  • Item 1
  • Item 2
  • Item 3

Inline list with spacing (none)

  • Item 1
  • Item 2
  • Item 3

Block list with spacing (xxsmall)

  • Item 1
  • Item 2
  • Item 3

Flex list with spacing (xxsmall)

  • Item 1
  • Item 2
  • Item 3

Inline list with spacing (xxsmall)

  • Item 1
  • Item 2
  • Item 3

Block list with spacing (xsmall)

  • Item 1
  • Item 2
  • Item 3

Flex list with spacing (xsmall)

  • Item 1
  • Item 2
  • Item 3

Inline list with spacing (xsmall)

  • Item 1
  • Item 2
  • Item 3

Block list with spacing (small)

  • Item 1
  • Item 2
  • Item 3

Flex list with spacing (small)

  • Item 1
  • Item 2
  • Item 3

Inline list with spacing (small)

  • Item 1
  • Item 2
  • Item 3

Block list with spacing (medium)

  • Item 1
  • Item 2
  • Item 3

Flex list with spacing (medium)

  • Item 1
  • Item 2
  • Item 3

Inline list with spacing (medium)

  • Item 1
  • Item 2
  • Item 3

Block list with spacing (large)

  • Item 1
  • Item 2
  • Item 3

Flex list with spacing (large)

  • Item 1
  • Item 2
  • Item 3

Inline 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 (xlarge)

  • Item 1
  • Item 2
  • Item 3

Inline list with spacing (xlarge)

  • Item 1
  • Item 2
  • Item 3

list separator variations

Block list with separators (solid)

Block list with separators (dashed)

Flex list with separators (solid)

Flex list with separators (dashed)

Inline list with separators (solid)

Inline list with separators (dashed)

list inset variations

Inset spacing is best suited for block and flex lists, even though you can apply to inline list as well.

Block list with inset spacing (xxsmall) and separators

Block list with inset spacing (xsmall) and separators

Block list with inset spacing (small) and separators

Block list with inset spacing (medium) and separators

Block list with inset spacing (large) and separators

Block list with inset spacing (xlarge) and separators

Flex list with inset spacing (xxsmall) and separators

Flex list with inset spacing (xsmall) and separators

Flex list with inset spacing (small) and separators

Flex list with inset spacing (medium) and separators

Flex list with inset spacing (large) and separators

Flex list with inset spacing (xlarge) and separators

Inline list with inset spacing (xxsmall) and separators

Inline list with inset spacing (xsmall) and separators

Inline list with inset spacing (small) and separators

Inline list with inset spacing (medium) and separators

Inline list with inset spacing (large) and separators

Inline list with inset spacing (xlarge) and separators

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 items: center

  • Item 1
  • Item 2
  • Item 3

Horizontally align inline items: end

  • 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 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="block" 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>