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.

v0.32.0AlphaReviewed for accessibility

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

NameTypeDefaultDescription
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(Primer::Alpha::ActionList::ARIA_SELECTION_VARIANT_OPTIONS) %?

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

Examples

Slots

heading

Heading text rendered above the list of items.

NameTypeDefaultDescription
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

NameTypeDefaultDescription
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

NameTypeDefaultDescription
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

NameTypeDefaultDescription
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

NameTypeDefaultDescription
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

NameTypeDefaultDescription
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

NameTypeDefaultDescription
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

Slots

description

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

NameTypeDefaultDescription
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.

NameTypeDefaultDescription
system_arguments
Hash

N/A

The arguments accepted by IconButton.

tooltip

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.

NameTypeDefaultDescription
type
Symbol

:description

One of :description or :label.

system_arguments
Hash

N/A

The arguments accepted by Tooltip.

Methods

id

Returns the value of attribute id.

item_id

Returns the value of attribute item_id.

list

Returns the value of attribute list.

href

Returns the value of attribute href.

active

Returns the value of attribute active.

disabled

Returns the value of attribute disabled.

parent

Returns the value of attribute parent.

active?

Returns the value of attribute active. Whether or not this item is active.

disabled?

Returns the value of attribute disabled. Whether or not this item is disabled.

ActionList::Heading

Heading used to describe each sub list within an action list.

Arguments

NameTypeDefaultDescription
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

Methods

title_id

Returns the value of attribute title_id.

subtitle_id

Returns the value of attribute subtitle_id.

ActionList::FormWrapper

Utility component for wrapping ActionLists or individual ActionList::Items in forms.

ActionList::Divider

Separator with optional text rendered above groups or between individual items.

Arguments

NameTypeDefaultDescription
scheme
Symbol

:subtle

Display a background color if scheme is filled.

system_arguments
Hash

N/A