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

Work in progressWe are currently transferring the Rails documentation for ActionList from a different site to this page. To view the original documentation, please visit the Primer ViewComponents documentation for ActionList.

v0.1.5AlphaNot reviewed 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

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`.
system_arguments	N/A	`Hash` System arguments

Examples

View in Lookbook

Slots

`heading`

Heading text rendered above the list of items.

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

`items`

Items.

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

Methods

`with_divider`

Adds a divider to the list of items.

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

`select_variant`

Returns the value of attribute select_variant.

`role`

Returns the value of attribute role.

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.
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.
truncate_label	`false`	`Boolean` Truncate label with ellipsis.
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.
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 avatar, call the with_leading_visual_avatar method, which accepts the arguments accepted by Avatar.

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

Name	Default	Description
id	`self.class.generate_id`	`String` The group's identifier (ID attribute in HTML).
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`.
tag	N/A	`Integer` Semantic tag for the heading.
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

Primer/Interface guidelines

Site navigation

Action list

Description

Arguments

Examples

Slots

`heading`

`items`

Methods

`with_divider`

`select_variant`

`role`

ActionList::Item

Arguments

Slots

`description`

`leading_visual`

`trailing_visual`

`trailing_action`

`tooltip`

Methods

`id`

`list`

`href`

`active`

`disabled`

`parent`

`active?`

`disabled?`

ActionList::Heading

Arguments

Methods

`id`

ActionList::Divider

Arguments