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	Default	Description
id	`self.class.generate_id`	`String` HTML ID value.
role	`nil`	`Boolean` ARIA role describing the function of the list. listbox and menu are a common values.
item_classes	`nil`	`String` Additional CSS classes to attach to items.
scheme	`:full`	`Symbol` 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	`false`	`Boolean` Display a divider above each item in the list when it does not follow a header or divider.
select_variant	`:none`	`Symbol` How items may be selected in the list. One of `:multiple`, `:multiple_checkbox`, `:none`, or `:single`.
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	N/A	`Hash` System arguments

Examples

Slots

`heading`

Heading text rendered above the list of items.

Name	Default	Description
component_klass	N/A	`Class` The class to use instead of the default ActionList::Heading.
system_arguments	N/A	`Hash` 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`

Adds an item to the list.

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

`with_divider`

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

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

`with_avatar_item`

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

Name	Default	Description
src	N/A	`String` The source url of the avatar image.
username	N/A	`String` The username associated with the avatar.
full_name	`nil`	`String` Optional. The user's full name.
full_name_scheme	`:block`	`Symbol` Optional. How to display the user's full name. One of `:block` or `:inline`.
component_klass	`ActionList::Item`	`Class` The class to use instead of the default ActionList::Item
avatar_arguments	`{}`	`Hash` Optional. The arguments accepted by Avatar
system_arguments	N/A	`Hash` 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.

`build_item`

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.

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

`build_avatar_item`

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.

Name	Default	Description
src	N/A	`String` The source url of the avatar image.
username	N/A	`String` The username associated with the avatar.
full_name	`nil`	`String` Optional. The user's full name.
full_name_scheme	`:block`	`Symbol` Optional. How to display the user's full name. One of `:block` or `:inline`.
component_klass	`ActionList::Item`	`Class` The class to use instead of the default ActionList::Item
avatar_arguments	`{}`	`Hash` Optional. The arguments accepted by Avatar
system_arguments	N/A	`Hash` 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	Default	Description
list	N/A	`Primer::Alpha::ActionList` The list that contains this item. Used internally.
parent	`nil`	`Primer::Alpha::ActionList::Item` This item's parent item. `nil` if this item is at the root. Used internally.
label	`nil`	`String` Item label. If no label is provided, content is used.
item_id	`nil`	`String` 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	`nil`	`String` 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	`:none`	`Boolean \| Symbol` 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	`nil`	`String` Link URL.
role	`nil`	`String` ARIA role describing the function of the item.
size	`:medium`	`Symbol` Controls block sizing of the item.
scheme	`:default`	`Symbol` Controls color/style based on behavior.
disabled	`false`	`Boolean` Disabled items are not clickable and visually dim.
description_scheme	`:block`	`Symbol` Display description inline with label, or block on the next line. One of `:block` or `:inline`.
active	`false`	`Boolean` If the parent list's `select_variant` is set to `:single` or `:multiple`, causes this item to render checked.
on_click	`nil`	`String` JavaScript to execute when the item is clicked.
id	`self.class.generate_id`	`String` Used internally.
system_arguments	N/A	`Hash` System arguments

Slots

`description`

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

`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	Default	Description
system_arguments	N/A	`Hash` 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	Default	Description
type	`:description`	`Symbol` One of `:description` or `:label`.
system_arguments	N/A	`Hash` The arguments accepted by Tooltip.

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

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

Site navigation

Action list

On this page