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.
On this page
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 |
| 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 |
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 |
form_arguments |
| Hash Allows an |
system_arguments | N/A | Hash |
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 |
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 |
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 |
| String Optional. The user's full name. |
full_name_scheme |
| Symbol Optional. How to display the user's full name. One of |
component_klass |
| 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 |
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 |
| 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 |
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 |
| String Optional. The user's full name. |
full_name_scheme |
| Symbol Optional. How to display the user's full name. One of |
component_klass |
| 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 |
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 |
| Primer::Alpha::ActionList::Item This item's parent item. |
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 |
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 |
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 |
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 |
active |
| Boolean If the parent list's |
on_click |
| String JavaScript to execute when the item is clicked. |
id |
| String Used internally. |
system_arguments | N/A | Hash |
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
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 |
| Symbol One of |
system_arguments | N/A | Hash 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
Name | Default | Description |
---|---|---|
title | N/A | String Sub list title. |
heading_level |
| Integer Heading level. Level 2 results in an |
subtitle |
| String Optional sub list description. |
scheme |
| Symbol Display a background color if scheme is |
system_arguments | N/A | Hash |
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
Name | Default | Description |
---|---|---|
scheme |
| Symbol Display a background color if scheme is |
system_arguments | N/A | Hash |