Action list

Action list is a vertical list of interactive actions or options. It's composed of items presented in a consistent, single-column format, with room for icons, descriptions, side information, and other rich visuals.

Description

An ActionList is a styled list of links. It acts as the base component for many other menu-type components, including ActionMenu and SelectPanel, as well as the navigational component NavList.

Each item in an action list can be augmented by specifying corresponding leading and/or trailing visuals.

Arguments

Name	Type	Default	Description
id	`String`	`self.class.generate_id`	HTML ID value.
role	`Boolean`	`nil`	ARIA role describing the function of the list. listbox and menu are a common values.
item_classes	`String`	`nil`	Additional CSS classes to attach to items.
scheme	`Symbol`	`:full`	One of `:full` or `:inset`. `inset` children are offset (vertically and horizontally) from list edges. `full` (default) children are flush (vertically and horizontally) with list edges.
show_dividers	`Boolean`	`false`	Display a divider above each item in the list when it does not follow a header or divider.
select_variant	`Symbol`	`:none`	How items may be selected in the list. One of `:multiple`, `:multiple_checkbox`, `:none`, or `:single`.
aria_selection_variant	`Symbol`	`:checked`	Specifies which aria selection to use. One of `:checked` or `:selected`.
form_arguments	`Hash`	`{}`	Allows an `ActionList` to act as a select list in multi- and single-select modes. Pass the `builder:` and `name:` options to this hash. `builder:` should be an instance of `ActionView::Helpers::FormBuilder`, which are created by the standard Rails `#form_with` and `#form_for` helpers. The `name:` option is the desired name of the field that will be included in the params sent to the server on form submission. NOTE: Consider using an ActionMenu instead of using this feature directly.
system_arguments	`Hash`	N/A	System arguments

Examples

Slots

`heading`

Heading text rendered above the list of items.

Name	Type	Default	Description
component_klass	`Class`	N/A	The class to use instead of the default ActionList::Heading.
system_arguments	`Hash`	N/A	The arguments accepted by `component_klass`.

`items`

Items. Items can be individual items, avatar items, or dividers. See the documentation for #with_item, #with_divider, and #with_avatar_item respectively for more information.

Methods

`with_item(component_klass: Class, system_arguments: Hash)`

Adds an item to the list.

Parameters

Name	Type	Default	Description
component_klass	`Class`	N/A	The class to use instead of the default ActionList::Item
system_arguments	`Hash`	N/A	These arguments are forwarded to ActionList::Item, or whatever class is passed as the `component_klass` argument.

`with_divider(system_arguments: Hash)`

Adds a divider to the list. Dividers visually separate items.

Parameters

Name	Type	Default	Description
system_arguments	`Hash`	N/A	The arguments accepted by ActionList::Divider.

`with_avatar_item(src: String, username: String, full_name: String, full_name_scheme: Symbol, component_klass: Class, avatar_arguments: Hash, system_arguments: Hash)`

Adds an avatar item to the list. Avatar items are a convenient way to accessibly add an item with a leading avatar image.

Parameters

Name	Type	Default	Description
src	`String`	N/A	The source url of the avatar image.
username	`String`	N/A	The username associated with the avatar.
full_name	`String`	`nil`	Optional. The user's full name.
full_name_scheme	`Symbol`	`:block`	Optional. How to display the user's full name. One of `:block` or `:inline`.
component_klass	`Class`	`ActionList::Item`	The class to use instead of the default ActionList::Item
avatar_arguments	`Hash`	`{}`	Optional. The arguments accepted by Avatar
system_arguments	`Hash`	N/A	These arguments are forwarded to ActionList::Item, or whatever class is passed as the `component_klass` argument.

`id`

Returns the value of attribute id.

`select_variant`

Returns the value of attribute select_variant.

`role`

Returns the value of attribute role.

`aria_selection_variant`

Returns the value of attribute aria_selection_variant.

`build_item(component_klass: Class, system_arguments: Hash)`

Builds a new item but does not add it to the list. Use this method instead of the #with_item slot if you need to render an item outside the context of a list, eg. if rendering additional items to append to an existing list, perhaps via a separate HTTP request.

Parameters

Name	Type	Default	Description
component_klass	`Class`	`ActionList::Item`	The class to use instead of the default ActionList::Item
system_arguments	`Hash`	N/A	These arguments are forwarded to ActionList::Item, or whatever class is passed as the `component_klass` argument.

`build_avatar_item(src: String, username: String, full_name: String, full_name_scheme: Symbol, component_klass: Class, avatar_arguments: Hash, system_arguments: Hash)`

Builds a new avatar item but does not add it to the list. Avatar items are a convenient way to accessibly add an item with a leading avatar image. Use this method instead of the #with_avatar_item slot if you need to render an avatar item outside the context of a list, eg. if rendering additional items to append to an existing list, perhaps via a separate HTTP request.

Parameters

Name	Type	Default	Description
src	`String`	N/A	The source url of the avatar image.
username	`String`	N/A	The username associated with the avatar.
full_name	`String`	`nil`	Optional. The user's full name.
full_name_scheme	`Symbol`	`:block`	Optional. How to display the user's full name. One of `:block` or `:inline`.
component_klass	`Class`	`ActionList::Item`	The class to use instead of the default ActionList::Item
avatar_arguments	`Hash`	`{}`	Optional. The arguments accepted by Avatar
system_arguments	`Hash`	N/A	These arguments are forwarded to ActionList::Item, or whatever class is passed as the `component_klass` argument.

`post_list_content_block`

Returns the value of attribute post_list_content_block.

ActionList::Item

An individual ActionList item. Items can optionally include leading and/or trailing visuals, such as icons, avatars, and counters.

Arguments

Name	Type	Default	Description
list	`Primer::Alpha::ActionList`	N/A	The list that contains this item. Used internally.
parent	`Primer::Alpha::ActionList::Item`	`nil`	This item's parent item. `nil` if this item is at the root. Used internally.
label	`String`	`nil`	Item label. If no label is provided, content is used.
item_id	`String`	`nil`	An ID that will be attached to the item's `<li>` element as `data-item-id` for distinguishing between items, perhaps in JavaScript.
label_classes	`String`	`nil`	CSS classes that will be added to the label.
label_arguments	`Hash`	`{}`	System arguments used to construct the label.
content_arguments	`Hash`	`{}`	System arguments used to construct the item's anchor or button tag.
form_arguments	`Hash`	`{}`	Allows the item to submit a form on click. The URL passed in the `href:` option will be used as the form action. Pass the `method:` option to this hash to control what kind of request is made, One of `:delete`, `:get`, `:head`, `:patch`, `:post`, or `:put`. The `name:` option is required and specifies the desired name of the field that will be included in the params sent to the server on form submission. Specify the `value:` option to send a custom value to the server; otherwise the value of `name:` is sent.
truncate_label	`Boolean \| Symbol`	`:none`	How the label should be truncated when the text does not fit inside the bounds of the list item. One of `false`, `:none`, `:show_tooltip`, `:truncate`, or `true`. Pass `false` or `:none` to wrap label text. Pass `true` or `:truncate` to truncate labels with ellipses. Pass `:show_tooltip` to show the entire label contents in a tooltip when the item is hovered.
href	`String`	`nil`	Link URL.
role	`String`	`nil`	ARIA role describing the function of the item.
size	`Symbol`	`:medium`	Controls block sizing of the item.
scheme	`Symbol`	`:default`	Controls color/style based on behavior.
disabled	`Boolean`	`false`	Disabled items are not clickable and visually dim.
description_scheme	`Symbol`	`:block`	Display description inline with label, or block on the next line. One of `:block` or `:inline`.
active	`Boolean`	`false`	If the parent list's `select_variant` is set to `:single` or `:multiple`, causes this item to render checked.
on_click	`String`	`nil`	JavaScript to execute when the item is clicked.
id	`String`	`self.class.generate_id`	Used internally.
system_arguments	`Hash`	N/A	System arguments

Slots

`description`

Description content that complements the item's label, with optional test_selector. See ActionList's description_scheme argument for layout options.

Name	Type	Default	Description
legacy_content	`String`	N/A	Slot content, provided for backwards-compatibility. Pass a content block instead, or call `with_content`, eg. `component.with_description { "My description" }` or `component.with_description.with_content("My description")`.
test_selector	`String`	N/A	The value of this argument is set as the value of a `data-test-selector` HTML attribute on the description element.

`leading_visual`

An icon, avatar, SVG, or custom content that will render to the left of the label.

To render an icon, call the with_leading_visual_icon method, which accepts the arguments accepted by Octicon.

To render an SVG, call the with_leading_visual_svg method.

To render custom content, call the with_leading_visual_content method and pass a block that returns a string.

`trailing_visual`

An icon, label, counter, or text to render to the right of the label.

To render an icon, call the with_leading_visual_icon method, which accepts the arguments accepted by Octicon.

To render a label, call the with_leading_visual_label method, which accepts the arguments accepted by Label.

To render a counter, call the with_leading_visual_counter method, which accepts the arguments accepted by Counter.

To render text, call the with_leading_visual_text method and pass a block that returns a string. Eg:


with_leading_visual_text { "Text here" }

`trailing_action`

A button rendered after the trailing icon that can be used to show a menu, activate a dialog, etc.

Name	Type	Default	Description
system_arguments	`Hash`	N/A	The arguments accepted by IconButton.

Tooltip that appears on mouse hover or keyboard focus over the trailing action button. Use tooltips sparingly and as a last resort. Important: This tooltip defaults to type: :description. In a few scenarios, type: :label may be more appropriate. Consult the Tooltip documentation for more information.

Name	Type	Default	Description
type	`Symbol`	`:description`	One of `:description` or `:label`.
system_arguments	`Hash`	N/A	The arguments accepted by Tooltip.

Name	Type	Default	Description
title	`String`	N/A	Sub list title.
heading_level	`Integer`	`3`	Heading level. Level 2 results in an `<h2>` tag, level 3 an `<h3>` tag, etc.
subtitle	`String`	`nil`	Optional sub list description.
scheme	`Symbol`	`:subtle`	Display a background color if scheme is `filled`.
system_arguments	`Hash`	N/A	System arguments

Name	Type	Default	Description
scheme	`Symbol`	`:subtle`	Display a background color if scheme is `filled`.
system_arguments	`Hash`	N/A	System arguments

Site navigation

Action list

On this page