Select panel

The Select Panel is an anchored dialog that allows users to quickly navigate and select one or multiple items from a list. It includes a text input for filtering, supports item grouping, and offers a footer for additional actions. Changes are applied upon closing the panel.

v0.34.0AlphaNot reviewed for accessibility

Description

Select panels allow for selecting from a large number of options and can be thought of as a more capable version of the traditional HTML <select> element.

Select panels:

  1. feature an input field at the top that allows an end user to filter the list of results.
  2. can render their items statically or dynamically by fetching results from the server.
  3. allow selecting a single item or multiple items.
  4. permit leading visuals like Octicons, avatars, and custom SVGs.
  5. can be used as form inputs in Rails forms.

Static list items

The Rails SelectPanel component allows items to be provided statically or loaded dynamically from the server. Providing items statically is done using a fetch strategy of :local in combination with the item slot:

<%= render(Primer::Alpha::SelectPanel.new(fetch_strategy: :local))) do |panel| %>
<% panel.with_show_button { "Select item" } %>
<% panel.with_item(label: "Item 1") %>
<% panel.with_item(label: "Item 2") %>
<% end %>

Dynamic list items

List items can also be fetched dynamically from the server and will require creating a Rails controller action to respond with the list of items in addition to rendering the SelectPanel instance. Render the instance as normal, providing your desired fetch strategy:

<%= render(
Primer::Alpha::SelectPanel.new(
fetch_strategy: :remote,
src: search_items_path # perhaps a Rails URL helper
)
) %>

Define a controller action to serve the list of items. The SelectPanel component passes any filter text in the q= URL parameter.

class SearchItemsController < ApplicationController
def show
# NOTE: params[:q] may be nil since there is no filter string available
# when the panel is first opened
@results = SomeModel.search(params[:q] || "")
end
end

Responses must be HTML fragments, eg. have a content type of text/html+fragment. This content type isn't available by default in Rails, so you may have to register it eg. in an initializer:

Mime::Type.register("text/fragment+html", :html_fragment)

Render a Primer::Alpha::SelectPanel::ItemList in the action's template, search_items/show.html_fragment.erb:

<%= render(Primer::Alpha::SelectPanel::ItemList.new) do |list| %>
<% @results.each do |result| %>
<% list.with_item(label: result.title) do |item| %>
<% item.with_description(result.description) %>
<% end %>
<% end %>
<% end %>

Selection consistency

The SelectPanel component automatically "remembers" which items have been selected across item fetch requests, meaning the controller that renders dynamic list items does not (and should not) remember these selections or persist them until the user has confirmed them, either by submitting the form or otherwise indicating completion. The SelectPanel component does not include unconfirmed selection data in requests.

Fetch strategies

The list of items can be fetched from a remote URL, or provided as a static list, configured using the fetch_strategy attribute. Fetch strategies are summarized below.

  1. :remote: a query is made to the URL in the src attribute every time the input field changes.

  2. :eventually_local: a query is made to the URL in the src attribute when the panel is first opened. The results are "remembered" and filtered in-memory for all subsequent filter operations, i.e. when the input field changes.

  3. :local: the list of items is provided statically ahead of time and filtered in-memory. No requests are made to the server.

Customizing filter behavior

If the fetch strategy is :remote, then filtering is handled server-side. The server should render a Primer::Alpha::SelectPanel::ItemList (an alias of ActionList) in the response containing the filtered list of items. The component achieves remote fetching via the remote-input-element, which sends a request to the server with the filter string in the q= parameter. Responses must be HTML fragments, eg. have a content type of text/html+fragment.

Local filtering

If the fetch strategy is :local or :eventually_local, filtering is performed client-side. Filter behavior can be customized in JavaScript by setting the filterFn attribute on the instance of SelectPanelElement, eg:

document.querySelector("select-panel").filterFn = (item: HTMLElement, query: string): boolean => {
// return true if the item should be displayed, false otherwise
}

The element's default filter function uses the value of the data-filter-string attribute, falling back to the element's innerText property. It performs a case-insensitive substring match against the filter string.

SelectPanels as form inputs

SelectPanels can be used as form inputs. They behave very similarly to how HTML <select> boxes behave, and play nicely with Rails' built-in form mechanisms. Pass arguments via the form_arguments: argument, including the Rails form builder object and the name of the field. Each list item must also have a value specified in content_arguments: { data: { value: } }.

<% form_with(model: Address.new) do |f| %>
<%= render(Primer::Alpha::SelectPanel.new(form_arguments: { builder: f, name: "country" })) do |menu| %>
<% countries.each do |country|
<% menu.with_item(label: country.name, content_arguments: { data: { value: country.code } }) %>
<% end %>
<% end %>
<% end %>

The value of the data: { value: ... } argument is sent to the server on submit, keyed using the name provided above (eg. "country"). If no value is provided for an item, the value of that item is the item's label. Here's the corresponding AddressesController that might be written to handle the form above:

class AddressesController < ApplicationController
def create
puts "You chose #{address_params[:country]} as your country"
end
private
def address_params
params.require(:address).permit(:country)
end
end

If items are provided dynamically, things become a bit more complicated. The form_for or form_with method call happens in the view that renders the SelectPanel, which means the form builder object but isn't available in the view that renders the list items. In such a case, it can be useful to create an instance of the form builder maually:

<% builder = ActionView::Helpers::FormBuilder.new(
"address", # the name of the model, used to wrap input names, eg 'address[country]'
nil, # object (eg. the Address instance, which we can omit)
self, # template
{} # options
) %>
<%= render(Primer::Alpha::SelectPanel::ItemList.new(
form_arguments: { builder: builder, name: "country" }
)) do |list| %>
<% countries.each do |country| %>
<% menu.with_item(label: country.name, content_arguments: { data: { value: country.code } }) %>
<% end %>
<% end %>

JavaScript API

SelectPanels render a <select-panel> custom element that exposes behavior to the client.

Utility methods

  • show(): Manually open the panel. Under normal circumstances, a show button is used to show the panel, but this method exists to support unusual use-cases.
  • hide(): Manually hides (closes) the panel.

Query methods

  • getItemById(itemId: string): Element: Returns the item's HTML <li> element. The return value can be passed as the item argument to the other methods listed below.
  • isItemChecked(item: Element): boolean: Returns true if the item is checked, false otherwise.
  • isItemHidden(item: Element): boolean: Returns true if the item is hidden, false otherwise.
  • isItemDisabled(item: Element): boolean: Returns true if the item is disabled, false otherwise.

NOTE: Item IDs are special values provided by the user that are attached to SelectPanel list items as the data-item-id HTML attribute. Item IDs can be provided by passing an item_id: attribute when adding items to the panel, eg:

<%= render(Primer::Alpha::SelectPanel.new) do |panel| %>
<% panel.with_item(item_id: "my-id") %>
<% end %>

The same is true when rendering ItemLists:

<%= render(Primer::Alpha::SelectPanel::ItemList.new) do |list| %>
<% list.with_item(item_id: "my-id") %>
<% end %>

State methods

  • enableItem(item: Element): Enables the item, i.e. makes it clickable by the mouse and keyboard.
  • disableItem(item: Element): Disables the item, i.e. makes it unclickable by the mouse and keyboard.
  • checkItem(item: Element): Checks the item. Only has an effect in single- and multi-select modes.
  • uncheckItem(item: Element): Unchecks the item. Only has an effect in multi-select mode, since items cannot be unchecked in single-select mode.

Events

NameTypeBubblesCancelable
itemActivatedCustomEvent<ItemActivatedEvent>YesNo
beforeItemActivatedCustomEvent<ItemActivatedEvent>YesYes
dialog:openCustomEvent<{dialog: HTMLDialogElement}>NoNo
panelClosedCustomEvent<{panel: SelectPanelElement}>YesNo

Item activation

The <select-panel> element fires an itemActivated event whenever an item is activated (eg. clicked) via the mouse or keyboard.

document.querySelector("select-panel").addEventListener(
"itemActivated",
(event: CustomEvent<ItemActivatedEvent>) => {
event.detail.item // Element: the <li> item that was activated
event.detail.checked // boolean: whether or not the result of the activation checked the item
}
)

The beforeItemActivated event fires before an item is activated. Canceling this event will prevent the item from being activated.

document.querySelector("select-panel").addEventListener(
"beforeItemActivated",
(event: CustomEvent<ItemActivatedEvent>) => {
event.detail.item // Element: the <li> item that was activated
event.detail.checked // boolean: whether or not the result of the activation checked the item
event.preventDefault() // Cancel the event to prevent activation (eg. checking/unchecking)
}
)

Arguments

NameTypeDefaultDescription
src
String

nil

The URL to fetch search results from.

title
String

"Menu"

The title that appears at the top of the panel.

id
String

self.class.generate_id

The unique ID of the panel.

size
Symbol

:small

The size of the panel. One of :auto, :large, :medium, :medium_portrait, :small, or :xlarge.

select_variant
Symbol

:single

One of :multiple, :none, or :single.

fetch_strategy
Symbol

:remote

One of :eventually_local, :local, or :remote.

no_results_label
String

"No results found"

The label to display when no results are found.

preload
Boolean

false

Whether to preload search results when the page loads. If this option is false, results are loaded when the panel is opened.

dynamic_label
Boolean

false

Whether or not to display the text of the currently selected item in the show button.

dynamic_label_prefix
String

nil

If provided, the prefix is prepended to the dynamic label and displayed in the show button.

dynamic_aria_label_prefix
String

nil

If provided, the prefix is prepended to the dynamic label and set as the value of the aria-label attribute on the show button.

body_id
String

nil

The unique ID of the panel body. If not provided, the body ID will be set to the panel ID with a "-body" suffix.

list_arguments
Hash

{}

Arguments to pass to the underlying ActionList component. Only has an effect for the local fetch strategy.

form_arguments
Hash

{}

Form arguments to pass to the underlying ActionList component. Only has an effect for the local fetch strategy.

show_filter
Boolean

true

Whether or not to show the filter input.

open_on_load
Boolean

false

Open the panel when the page loads.

anchor_align
Symbol

:start

The anchor alignment of the Overlay. One of :center, :end, or :start.

anchor_side
Symbol

:outside_bottom

The side to anchor the Overlay to. One of :inside_bottom, :inside_center, :inside_left, :inside_right, :inside_top, :outside_bottom, :outside_left, :outside_right, or :outside_top.

system_arguments
Hash

N/A

Examples

Slots

Renders content in a footer region below the list of items.

NameTypeDefaultDescription
system_arguments
Hash

N/A

The arguments accepted by Dialog::Footer.

subtitle

Renders content underneath the title at the top of the panel.

NameTypeDefaultDescription
system_arguments
Hash

N/A

The arguments accepted by Dialog::Header's subtitle slot.

show_button

Adds a show button (i.e. a button) that will open the panel when clicked.

NameTypeDefaultDescription
system_arguments
Hash

N/A

The arguments accepted by Button.

preload_error_content

Customizable content for the error message that appears when items are fetched for the first time. This message appears in place of the list of items. For more information, see the documentation regarding SelectPanel error messaging.

error_content

Customizable content for the error message that appears when items are fetched as the result of a filter operation. This message appears as a banner above the previously fetched list of items. For more information, see the documentation regarding SelectPanel error messaging.

Methods

src -> String

The URL to fetch search results from.

panel_id -> String

The unique ID of the panel.

body_id -> String

The unique ID of the panel body.

select_variant -> Symbol

One of :multiple, :none, or :single.

fetch_strategy -> Symbol

One of :eventually_local, :local, or :remote.

preload -> Boolean

Whether to preload search results when the page loads. If this option is false, results are loaded when the panel is opened.

preload? -> Boolean

Whether to preload search results when the page loads. If this option is false, results are loaded when the panel is opened.

show_filter -> Boolean

Whether or not to show the filter input.

show_filter? -> Boolean

Whether or not to show the filter input.

with_item(system_arguments: Hash)

Adds an item to the list. Note that this method only has an effect for the local fetch strategy.

Parameters

NameTypeDefaultDescription
system_arguments
Hash

N/A

The arguments accepted by ActionList's item slot.

SelectPanel::ItemList

The component that should be used to render the list of items in the body of a SelectPanel.

Arguments

NameTypeDefaultDescription
system_arguments
Hash

N/A

The arguments accepted by ActionList.

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.