ActionList

readyReviewed for a11y

This page may be removed. Primer plans to move all Rails component documentation to Lookbook.

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	Required	Description
id		`String` HTML ID value.
role		`Boolean` ARIA role describing the function of the list. listbox and menu are a common values.
item_classes		`String` Additional CSS classes to attach to items.
scheme		`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		`Boolean` Display a divider above each item in the list when it does not follow a header or divider.
select_variant		`Symbol` How items may be selected in the list. One of `:multiple`, `:multiple_checkbox`, `:none`, or `:single`.
aria_selection_variant		`Symbol` 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 `Primer::Alpha::ActionMenu` instead of using this feature directly.
system_arguments		`Hash` System arguments

Slots

`heading`

Heading text rendered above the list of items.

Name	Required	Description
component_klass		`Class` The class to use instead of the default `Primer::Alpha::ActionList::Heading`.
system_arguments		`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(component_klass: Class, system_arguments: Hash)`

Adds an item to the list.

Parameters

Name	Required	Description
component_klass		`Class` The class to use instead of the default `Primer::Alpha::ActionList::Item`
system_arguments		`Hash` These arguments are forwarded to `Primer::Alpha::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	Required	Description
system_arguments		`Hash` The arguments accepted by `Primer::Alpha::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	Required	Description
src		`String` The source url of the avatar image.
username		`String` The username associated with the avatar.
full_name		`String` Optional. The user's full name.
full_name_scheme		`Symbol` Optional. How to display the user's full name. One of `:block` or `:inline`.
component_klass		`Class` The class to use instead of the default `Primer::Alpha::ActionList::Item`
avatar_arguments		`Hash` Optional. The arguments accepted by `Primer::Beta::Avatar`
system_arguments		`Hash` These arguments are forwarded to `Primer::Alpha::ActionList::Item`, or whatever class is passed as the `component_klass` argument.

`select_variant`

Returns the value of attribute select_variant.

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

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

To render a counter, call the with_leading_visual_counter method, which accepts the arguments accepted by Primer::Beta::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	Required	Description
system_arguments		`Hash` The arguments accepted by `Primer::Beta::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 Primer::Alpha::Tooltip documentation for more information.

Name	Required	Description
type		`Symbol` One of `:description` or `:label`.
system_arguments		`Hash` The arguments accepted by `Primer::Alpha::Tooltip`.

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

Name	Required	Description
scheme		`Symbol` Display a background color if scheme is `filled`.
system_arguments		`Hash` System arguments