List

Semantic list for displaying a group of items.

Usage recommendations

Recommended	Not Recommended
List Related Items: Stick to items that belong in the same category or serve a similar function.	Skip Complexity: Avoid embedding complex structures like nested lists or other HTML elements unless essential.
Order Matters: If the sequence is important, use an ordered list. Otherwise, an unordered list will suffice.	Not for Layout: Don't use lists for page layout or to achieve visual design effects.
Concise Items: Keep list items short and to the point for easy scanning.	Avoid Mixing Types: Stick to either ordered or unordered lists within a single list block to prevent confusion.

Twig Usage

{% set list_items %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_1,
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_2,
  } only %}
  ...
{% include '@bolt-elements-list/list.twig' with {
  content: list_items
} only %}

Schema

List (list.twig)

Prop Name	Description	Type	Default Value	Option(s)
attributes	A Drupal-style attributes object with extra attributes to append to this element.	`object`	—	—
content	Content of the List. List Items are expected here.	`any`	—	—
tag	Set the semantic tag for the list, or `span` for a specific usecase	`string`	`ul`	`ul`, `ol`, `span`
display	Display either an horizontal list of items or a vertical list of items. Responsive options are also available for transforming from block to horizontal at specific breakpoints.	`string`	`vertical`	`vertical`, `horizontal`, `horizontal@xxsmall`, `horizontal@xsmall`, `horizontal@small`, `horizontal@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`
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`
inset	Set spacing on the inside of each item.	`boolean`	`false`	—
nowrap	Prevent horizontal/flex list items from wrapping to a second line.	`boolean`	`false`	—

List Item (list-item.twig)

Prop Name	Description	Type	Default Value	Option(s)
attributes	A Drupal-style attributes object with extra attributes to append to this element.	`object`	—	—
content	Content of the List Item.	`any`	—	—

Install

npm install @bolt/elements-list

Dependencies

@bolt/core

Basic List

The List element represents a list of items.

Demo

Item 1
Item 2
Item 3

Twig

{% set list_items %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: 'item 1',
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: 'item 2',
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: 'item 3',
  } only %}
{% endset %}

{% include '@bolt-elements-list/list.twig' with {
  content: list_items
} only %}

HTML

<ul class="e-bolt-list">
  <li class="e-bolt-list__item">Item 1</li>
  <li class="e-bolt-list__item">Item 2</li>
  <li class="e-bolt-list__item">Item 3</li>
</ul>

List Tag

Choose between ul and ol tags when creating a List or span in a specific usecases.

Important Notes:

The ul tag is for grouping a collection of items that do not have a numerical ordering, and their order in the list is meaningless.

On the other hand, with the ol tag, the order is meaningful.

Sometimes a semantic list ul or ol need to be converted to non-semantic version due to design purposes - for achieving visual effect. Find special usecases when a span is used.

It's important to know that ul and ol have their own styles. When using span tag, font-family, font-size, font-weight, line-height, inherit from parent element.

Demo

UL

Item
Item
Item

OL

Item 1
Item 2
Item 3

SPAN

Item

Twig

{% set list_items %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: 'first item',
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: 'second item',
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: 'third item',
  } only %}
{% endset %}

{% include '@bolt-elements-list/list.twig' with {
  tag: 'ol',
  content: list_items
} only %}

HTML

<ol class="e-bolt-list">
  <li class="e-bolt-list__item">First item</li>
  <li class="e-bolt-list__item">Second item</li>
  <li class="e-bolt-list__item">Third item</li>
</ol>

List Display

The display of the List Items can be set to vertical or horizontal.

Important Notes:

When the display prop is set to vertical, List Items are full-width, stacked on one another.

When the display prop is set to horizontal, List Items are side by side and take the width of the content. List Items can be of different widths if the content differs in length.

When the display prop is set to horizontal@[Breakpoint], List Items are vertical below the specified breakpoint (xxsmall, xsmall, small or medium) and horizontal above the breakpoint.

View the following Lists in different viewports to observe the behavior.

Demo

Vertical List Items are full-width.

Item One
Item Two
Item Three
Item Four
Item Five
Item Six

Horizontal List Items wrap and are only content-width.

Item One
Item Two
Item Three
Item Four
Item Five
Item Six
Item Seven
Item Eight
Item Nine
Item Ten

A `horizontal@medium` List is horizontal above the chosen breakpoint and vertical below.

Item One
Item Two
Item Three
Item Four
Item Five
Item Six

Twig

{% set list_items %}
    {% include '@bolt-elements-list/list-item.twig' with {
      content: placeholder_1,
    } only %}
    {% include '@bolt-elements-list/list-item.twig' with {
      content: placeholder_2,
    } only %}
    {% include '@bolt-elements-list/list-item.twig' with {
      content: placeholder_3,
    } only %}
  {% endset %}
{% include '@bolt-elements-list/list.twig' with {
  display: 'horizontal',
  content: list_items
} only %}

HTML

<ul class="e-bolt-list e-bolt-list--display-horizontal">
  <li class="e-bolt-list__item">First item</li>
  <li class="e-bolt-list__item">Second item</li>
  <li class="e-bolt-list__item">Thitd item</li>
</ul>

List with No Wrapping

Prevent List Items from wrapping with the nowrap prop.

Demo

Horizontal list with nowrap

Item 1
Item 2
Item 3
Item 4
Item 5
Item 6
Item 7
Item 8
Item 9

Twig

{% set list_items %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_1,
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_2,
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_3,
  } only %}
  ...
{% endset %}
{% include '@bolt-elements-list/list.twig' with {
  display: 'horizontal',
  nowrap: true,
  content: list_items
} only %}

HTML

<ul class="e-bolt-list e-bolt-list--display-horizontal e-bolt-list--nowrap">
  <li class="e-bolt-list__item">First item</li>
  <li class="e-bolt-list__item">Second item</li>
  <li class="e-bolt-list__item">Third item</li>
  <li class="e-bolt-list__item">Fourth item</li>
  <li class="e-bolt-list__item">Fifth item</li>
  <li class="e-bolt-list__item">Sixth item</li>
  <li class="e-bolt-list__item">Seventh item</li>
  <li class="e-bolt-list__item">Eighth item</li>
  <li class="e-bolt-list__item">Ninth item</li>
</ul>

List Spacing

Modify the space between List Items.

Demo

Vertical list with spacing (none)

Item 1
Item 2
Item 3

Vertical list with spacing (xxsmall)

Item 1
Item 2
Item 3

Vertical list with spacing (xsmall)

Item 1
Item 2
Item 3

Vertical list with spacing (small)

Item 1
Item 2
Item 3

Vertical list with spacing (medium)

Item 1
Item 2
Item 3

Vertical list with spacing (large)

Item 1
Item 2
Item 3

Vertical list with spacing (xlarge)

Item 1
Item 2
Item 3

Horizontal list with spacing (none)

Item 1
Item 2
Item 3

Horizontal list with spacing (xxsmall)

Item 1
Item 2
Item 3

Horizontal list with spacing (xsmall)

Item 1
Item 2
Item 3

Horizontal list with spacing (small)

Item 1
Item 2
Item 3

Horizontal list with spacing (medium)

Item 1
Item 2
Item 3

Horizontal list with spacing (large)

Item 1
Item 2
Item 3

Horizontal list with spacing (xlarge)

Item 1
Item 2
Item 3

Twig

{% set list_items %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_1,
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_2,
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_3,
  } only %}
{% endset %}
{% include '@bolt-elements-list/list.twig' with {
  spacing: 'medium',
  content: list_items,
} only %}

HTML

<ul class="e-bolt-list e-bolt-list--spacing-medium">
  <li class="e-bolt-list__item">First item</li>
  <li class="e-bolt-list__item">Second item</li>
  <li class="e-bolt-list__item">Third item</li>
</ul>

List with Separator

List Items can be separated by a horizontal or vertical line. The separator style can be solid or dashed.

Demo

Solid separators in a vertical list

Item 1
Item 2
Item 3

Solid separators in a horizontal list

Item 1
Item 2
Item 3

Solid separators in a horizontal@medium list

Item 1
Item 2
Item 3

Dashed separators in a vertical list

Item 1
Item 2
Item 3

Dashed separators in a horizontal list

Item 1
Item 2
Item 3

Dashed separators in a horizontal@medium list

Item 1
Item 2
Item 3

Twig

{% set list_items %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: item_1,
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: item_2,
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: item_3,
  } only %}
{% endset %}
{% include '@bolt-elements-list/list.twig' with {
  separator: 'solid',
  content: list_items
} only %}

HTML

<ul class="e-bolt-list e-bolt-list--separator-solid">
  <li class="e-bolt-list__item">First item</li>
  <li class="e-bolt-list__item">Second item</li>
  <li class="e-bolt-list__item">Third item</li>
</ul>

List with Inset Spacing

Add inset spacing to List Items.

Demo

Regular spacing in a vertical list

Item 1
Item 2
Item 3

Inset spacing in a vertical list

Item 1
Item 2
Item 3

Regular spacing in a horizontal list

Item 1
Item 2
Item 3

Inset spacing in a horizontal list

Item 1
Item 2
Item 3

Regular spacing in a horizontal@medium list

Item 1
Item 2
Item 3

Inset spacing in a horizontal@medium list

Item 1
Item 2
Item 3

Twig

{% set list_items %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_1,
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_2,
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_3,
  } only %}
{% endset %}

{% include '@bolt-elements-list/list.twig' with {
  separator: 'solid',
  inset: true,
  content: list_items
} only %}

HTML

<ul class="e-bolt-list e-bolt-list--separator-solid e-bolt-list--inset">
  <li class="e-bolt-list__item">First item</li>
  <li class="e-bolt-list__item">Second item</li>
  <li class="e-bolt-list__item">Third item</li>
</ul>

List with Horizontal Alignment

Adjust the horizontal alignment of List Items.

Demo

Horizontally align horizontal content: start

Item 1
Item 2
Item 3

Horizontally align horizontal@medium content: start

Item 1
Item 2
Item 3

Horizontally align horizontal content: center

Item 1
Item 2
Item 3

Horizontally align horizontal@medium content: center

Item 1
Item 2
Item 3

Horizontally align horizontal content: end

Item 1
Item 2
Item 3

Horizontally align horizontal@medium content: end

Item 1
Item 2
Item 3

Horizontally align horizontal content: justify

Item 1
Item 2
Item 3

Horizontally align horizontal@medium content: justify

Item 1
Item 2
Item 3

Twig

{% set list_items %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_1,
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_2,
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: placeholder_3,
  } only %}
{% endset %}
{% include '@bolt-elements-list/list.twig' with {
  align: 'justify',
  content: list_items
} only %}

HTML

<ul class="e-bolt-list e-bolt-list--align-justify">
  <li class="e-bolt-list__item">First item</li>
  <li class="e-bolt-list__item">Second item</li>
  <li class="e-bolt-list__item">Third item</li>
</ul>

List with Vertical Alignment

Adjust the vertical alignment of List Items.

Demo

Vertically align horizontal content: start

Item 1
Item 2
Item 3

Vertically align horizontal@medium content: start

Item 1
Item 2
Item 3

Vertically align horizontal content: center

Item 1
Item 2
Item 3

Vertically align horizontal@medium content: center

Item 1
Item 2
Item 3

Vertically align horizontal content: end

Item 1
Item 2
Item 3

Vertically align horizontal@medium content: end

Item 1
Item 2
Item 3

Twig

{% include '@bolt-elements-list/list.twig' with {
  valign: 'start',
  content: list_items
} only %}

HTML

<ul class="e-bolt-list e-bolt-list--valign-start">
  <li class="e-bolt-list__item">First item</li>
  <li class="e-bolt-list__item">Second item</li>
  <li class="e-bolt-list__item">Third item</li>
</ul>

List Use Cases

The List element represents a list of items.

Demo

What we do

The Pega Platform™ makes it simpler for enterprises to work smarter, unify experiences, and adapt instantly. Thanks to our scalable, made-to-measure architecture, even the biggest organizations can stay streamlined and ready for what’s next.

Governance

One of the objectives of Pega is to build a fast-growing, profitable enterprise that rewards our employees, shareholders, and partners. To achieve this, we must continuously earn the trust of our many stakeholders: employees, customers, partners, suppliers, shareholders, government officials, and the general public.

Code of Conduct
Reporting Accounting Control Concerns
Related Person Transaction Policy
Audit Committee

Twig

{% set intro %}
  {% include '@bolt-elements-type/type.twig' with {
    content: 'What we do',
    hierarchy: 'headline',
    tag: 'h2',
    size: 'xxlarge',
  } only %}
  {% include '@bolt-elements-type/type.twig' with {
    content: 'The Pega Platform™ makes it simpler for enterprises to work smarter...',
  } only %}
  {% set list_items %}
    {% set button_1 %}
      {% include '@bolt-elements-button/button.twig' with {
        content: 'Explore products',
        attributes: {
          href: 'https://google.com',
        }
      } only %}
    {% endset %}
    {% include '@bolt-elements-list/list-item.twig' with {
      content: button_1,
    } only %}
    //More buttons if needed
  {% endset %}
  {% include '@bolt-elements-list/list.twig' with {
    display: 'horizontal',
    content: list_items,
  } only %}
{% endset %}
{% set layout_items %}
  {% include '@bolt-layouts-layout/layout-item.twig' with {
    content: intro
  } only %}
{% endset %}
{% include '@bolt-layouts-layout/layout.twig' with {
  content: layout_items,
  template: [
    '50@from-medium',
  ],
} only %}

HTML

<bolt-layout template="50@from-medium">
  <bolt-layout-item>
    <p class="e-bolt-type">
      The Pega Platform™ makes it simpler for enterprises to work smarter, unify experiences, and adapt instantly. Thanks to our scalable, made-to-measure architecture, even the biggest organizations can stay streamlined and ready for what’s next.</p>
    <ul class="e-bolt-list e-bolt-list--display-horizontal e-bolt-list--spacing-xsmall e-bolt-list--align-start e-bolt-list--valign-center">
      <li class="e-bolt-list__item">
        <a href="https://google.com" class="e-bolt-button">Explore products</a>
      </li>
      <li class="e-bolt-list__item">
      <a href="https://google.com" class="e-bolt-button e-bolt-button--secondary">Why Pega</a>
      </li>
    </ul>
  </bolt-layout-item>
</bolt-layout>

Non Semantic List Use Case

Using the span tag for lists in interactive elements and other non-semantic contexts.

Important Notes:

This has more of a decorative context than a semantic one or for organize content, making it more readable and visually balanced.

Sometimes there are situations where we need to create a list inside an interactive element, like a button. In these cases, we cannot use standard list tags like ul or ol because, for semantic reasons, certain HTML tags cannot be nested inside others. This is an example of when it's appropriate to use the span tag to wrap list items, ensuring both functionality and semantic correctness.

Additionally, there are other contexts where using ul or ol is not semantically appropriate, such as within specific structural or inline elements, and in such cases, the span tag offers a more suitable solution.

Demo

Lorem ipsum dolor sit amet..

Username Min. 6 characters Min. 1 capital letter

Headline link

Twig

{% set list_items %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: 'item 1',
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: 'item 2',
  } only %}
  {% include '@bolt-elements-list/list-item.twig' with {
    content: 'item 3',
  } only %}
{% endset %}

{% include '@bolt-elements-list/list.twig' with {
  content: list_items,
  tag: 'span'
} only %}

HTML

<span class="e-bolt-list">
  <span class="e-bolt-list__item">Item 1</li>
  <span class="e-bolt-list__item">Item 2</li>
  <span class="e-bolt-list__item">Item 3</li>
</span>

list

list docs Show Code Hide Code

List

Semantic list for displaying a group of items.

list Show Code Hide Code

list tag Show Code Hide Code

UL

OL

SPAN

list display Show Code Hide Code

Vertical List Items are full-width.

Horizontal List Items wrap and are only content-width.

A horizontal@medium List is horizontal above the chosen breakpoint and vertical below.

list nowrap Show Code Hide Code

Horizontal list with nowrap

list spacing Show Code Hide Code

Vertical list with spacing (none)

Vertical list with spacing (xxsmall)

Vertical list with spacing (xsmall)

Vertical list with spacing (small)

Vertical list with spacing (medium)

Vertical list with spacing (large)

Vertical list with spacing (xlarge)

Horizontal list with spacing (none)

Horizontal list with spacing (xxsmall)

Horizontal list with spacing (xsmall)

Horizontal list with spacing (small)

Horizontal list with spacing (medium)

Horizontal list with spacing (large)

Horizontal list with spacing (xlarge)

list separator Show Code Hide Code

Solid separators in a vertical list

Solid separators in a horizontal list

Solid separators in a horizontal@medium list

Dashed separators in a vertical list

Dashed separators in a horizontal list

Dashed separators in a horizontal@medium list

list inset Show Code Hide Code

Regular spacing in a vertical list

Inset spacing in a vertical list

Regular spacing in a horizontal list

Inset spacing in a horizontal list

Regular spacing in a horizontal@medium list

Inset spacing in a horizontal@medium list

list align Show Code Hide Code

Horizontally align horizontal content: start

Horizontally align horizontal@medium content: start

Horizontally align horizontal content: center

Horizontally align horizontal@medium content: center

Horizontally align horizontal content: end

Horizontally align horizontal@medium content: end

Horizontally align horizontal content: justify

Horizontally align horizontal@medium content: justify

list valign Show Code Hide Code

Vertically align horizontal content: start

Vertically align horizontal@medium content: start

Vertically align horizontal content: center

Vertically align horizontal@medium content: center

Vertically align horizontal content: end

Vertically align horizontal@medium content: end

list use cases Show Code Hide Code

What we do

Governance

Code of Conduct

Reporting Accounting Control Concerns

Related Person Transaction Policy

Audit Committee

list non semantic use case Show Code Hide Code

Headline link

list docs

list

list tag

list display

A `horizontal@medium` List is horizontal above the chosen breakpoint and vertical below.

list nowrap

list spacing

list separator

list inset

list align

list valign

list use cases

list non semantic use case