Nested menu
A nested menu provides multiple levels of categories with items for selection. Categories expand to reveal additional sub-items or options.
Overview
Resources
Install
yarn add @activecampaign/camp-components-nested-menuImplementation details
Install
items: ItemProps<T>[]The NestedMenu supports use as both a ‘uncontrolled’ or ‘controlled’ React component, however, consumers will likely want to track their ‘selection’ within state. Similarly to dropdown, NestedMenu supports dynamic ‘trigger’ elements. Unlike dropdown, we do not provide a ‘default’ trigger element, we expect the user to specify one. To specify the trigger, you simply can pass a ReactNode as the single ‘child’ of the NestedMenu:
type ItemProps<T> = {
/**
* determines if the item is a 'selectable' item, or just a styled 'menuGroup' with 'sub' items
*/
type: 'selectable' | 'menuGroup';
/**
* the generic 'value' of the list item
* - if the type is 'menuGroup', this will always be a string. else, this is type is inferred from the generic
*/
value: T;
/**
* the next layer of nesting
*/
items: ItemProps<T>[];
};The consumer needs to provide a list of these objects.
In the example below, the menuGroup options has a value of type string, and the selectable options values are objects. For menuGroup options which contain nested items, the value we want to display will always be a string. our ‘selectable’ value is ‘generic’, and can be any type.
export const timezone_objects: ItemProps<TimezoneObject>[] = [
{
type: 'menuGroup',
value: 'America', // because 'type' is set to 'menuGroup', the header 'value' just needs to be a string
items: [
{
type: 'selectable', // when the type is 'selectable', the 'value' is our generic type, `TimezoneObject`
value: {
state: 'New York City',
city: 'New York City',
timezone: 'Eastern Time Zone (ET)',
},
},
{
type: 'selectable',
value: {
state: 'California',
city: 'Los Angeles',
timezone: 'Pacific Time Zone (PT)',
},
},
{
type: 'selectable',
value: {
state: 'Illinois',
city: 'Chicago',
timezone: 'Central Time Zone (CT)',
},
},
{
type: 'selectable',
value: {
state: 'Texas',
city: 'Houston',
timezone: 'Central Time Zone (CT)',
},
},
{
type: 'selectable',
value: {
state: 'Arizona',
city: 'Phoenix',
timezone: 'Mountain Time Zone (MT)',
},
},
{
type: 'selectable',
value: {
state: 'Pennsylvania',
city: 'Philadelphia',
timezone: 'Eastern Time Zone (ET)',
},
},
{
type: 'selectable',
value: {
state: 'Texas',
city: 'San Antonio',
timezone: 'Central Time Zone (CT)',
},
},
{
type: 'selectable',
value: {
state: 'California',
city: 'San Diego',
timezone: 'Pacific Time Zone (PT)',
},
},
{
type: 'selectable',
value: {
state: 'Texas',
city: 'Dallas',
timezone: 'Central Time Zone (CT)',
},
},
{
type: 'selectable',
value: {
state: 'California',
city: 'San Jose',
timezone: 'Pacific Time Zone (PT)',
},
},
],
},
{
type: 'menuGroup',
value: 'Europe',
items: [
{
type: 'selectable',
value: {
country: 'France',
state: 'Île-de-France Region',
city: 'Paris',
timezone: 'Central European Time (CET)',
},
},
{
type: 'selectable',
value: {
country: 'Sweden',
city: 'Stockholm',
timezone: 'Central European Time (CET)',
},
},
],
},
];Item state
selected:TonSelectItem?: (changes: T) => voiditemToString?: (item: T) => stringWhen using the component in ‘controlled’ mode with React state, the component will infer the type of the state the user is setting, as well as the items being passed to the component. If we were to use timezone_objects from the previous code snippet:
const [state, setState] = React.useState<TimezoneObject>();
return (
<NestedMenu
onSelectItem={(option) => setState(option)} // 'option' should be of type TimezoneObject, this sets our state
itemToString={(obj) => obj.city} // this is required if `value` is not a string, as we need to determine what text is displayed in the option
items={timezone_objects} // our list of 'items'
selected={state} // our controlled state object
>
<IconButton icon="lightning" size="small" />
</NestedMenu>
);onSelectItem: this is what we’re using to actually set our state object, in this case, we’re setting the entire timezone object in our stateitemToString: this prop is only required if thevalueproperty for your item object is nottypeofstring, the reason we need this prop is to specify the displayed text within the list optionselected: we simply pass our React state object to this prop
Menu height
menuHeight?: MenuHeightOptionally, the NestedMenu supports the ability to override the height and maxHeight of the ‘menu window’ itself (the ul element). The MenuHeight object looks like this:
type MenuHeight = Partial<{
height: React.CSSProperties['height'];
maxHeight: React.CSSProperties['maxHeight'];
}>;Custom “no results” message
noSearchResultsMessage?: stringnoOptionsMessage?: stringOptionally, the NestedMenu supports rendering a custom ‘no results’ and ‘no options’ message to override the default ones.
return (
<NestedMenu
onSelectItem={(option) => setState(option)}
// items={pallete_strings} - will need to 'not' provide 'items' in order to see 'no options' message show up
selected={state}
noSearchResultsMessage="nothing find, try a different search term."
noOptionsMessage="you forgot to provide any 'items'!"
>
<IconButton icon="lightning" size="small" />
</NestedMenu>
);Custom content in a list item
renderCallbackOptionally specify a ‘render callback’ that enables rendering custom content within the list option.
(itemToStringText: string, option: T) => React.ReactNode;This is useful for when value is an object. The callback arguments exposes two values: itemToStringText: string, the required string required to use this prop, and option: T, the value for that particular list item.
<NestedMenu
onSelectItem={(option) => setState(option)}
itemToString={(obj) => obj.city}
renderCallback={(string, option) => (
<Styled>
{/* need to render `itemToString` returned value */}
<Styled>{string}</Styled>
{/* additional content */}
<Text.Body dangerouslySetStyles={{ color: 'slate400' }} appearance="xSmall">
{option.timezone}
</Text.Body>
</Styled>
)}
items={timezone_objects}
selected={state}
>
<IconButton icon="lightning" size="small" />
</NestedMenu>Setting up the trigger
A dropdown field or an icon button is most commonly used as the nested menu trigger.
NestedMenuDropdownTriggerThe NestedMenu exports out a special ‘trigger’ that allows it to function / appear similarly to the camp Dropdown component.
To set this up, simply import the NestedMenuDropdownTrigger alongside the NestedMenu, and pass it as a ‘child’ of the NestedMenu like so:
import { NestedMenu, NestedMenuDropdownTrigger } from '@activecampaign/camp-components-nested-menu'
const App = () => {
const [state, setState] = React.useState<string>();
return (
<NestedMenu
selected={state}
items={palette_strings}
onSelectItem={(option) => setState(option)}
{...props}
>
<NestedMenuDropdownTrigger
helperText="helper text for dropdown trigger"
label="Select an option"
placeholder="Select something"
/>
</NestedMenu>
)
}When using the NestedMenuDropdownTrigger and working with a list of objects, you’ll need to add the renderObjectCallback prop on the trigger in order to specify which field in the selection object to render within the trigger:
Loading State
The NestedMenuDropdownTrigger has a loading state that can be used by setting the loadingIndicator prop on the trigger component to true.
import { NestedMenu, NestedMenuDropdownTrigger } from '@activecampaign/camp-components-nested-menu'
const App = () => {
const [state, setState] = React.useState<string>();
const [isLoading, setIsLoading] = React.useState<boolean>(true);
return (
<NestedMenu
selected={state}
items={palette_strings}
onSelectItem={(option) => setState(option)}
{...props}
>
<NestedMenuDropdownTrigger
// control the loadingIndicator prop here
loadingIndicator={isLoading}
helperText="helper text for dropdown trigger"
label="Select an option"
placeholder="Select something"
/>
</NestedMenu>
)
}Adding a menu action
Similar to a dropdown, a nested menu can contain an action in the footer of the menu.
<NestedMenu
onSelectItem={(option) => setState(option)}
itemToString={(obj) => obj?.text}
items={formatted_items}
selected={state}
// return some jsx to render in the menu actions section
renderMenuActions={(onClose: () => void) => (
<Styled styles={{ display: 'flex' }}>
<Button.Fill
onClick={() => {
console.log('close menu!');
onClose();
}}
mr="sp200"
styles={{ width: '100%' }}
>
Trigger Close Callback
</Button.Fill>
</Styled>
)}
>
<NestedMenuDropdownTrigger
renderObjectCallback={(item: Selection) => item.selection}
helperText="helper text for dropdown trigger"
label="Nested Dropdown Trigger Label"
placeholder="Select"
/>
</NestedMenu>Usage
Best practices
- Dropdown menus work best for small data sets where a user has anywhere from 5 to 15 items to choose from. For smaller datasets, checkboxes or radios should be used (depending on single or multiselect), and for datasets larger than 15, it is recommended to use a combobox instead.
- When grouped, liste items should be in some logical order that makes it easy for the user to read and understand, whether that is numerical or alphabetical or some other contextually-based grouping.
Accessibility
Keyboard support
Tabor (shift+tabto move backward) opens and closes the menu and moves focus. If the menu is closed the input is in focus, thentabwill navigate to the next element in the tab order.- To open the dropdown on focus, press
spaceto open the menu. When the dropdown menu is open, use↑or↓to navigate list items andenterto select or deselect an item within the list. When selecting items, the menu closes after selecting in a single select dropdown but remains open in a multiselect dropdown. ↑or↓can also be used to open a closed dropdown menu.- If a multiselect dropdown has a search, upon open of the dropdown, the search input is in focus. Search can either be navigated away from using
tabor arrow keys. escwill close the dropdown when focused anywhere inside the component.- Entering search terms will either yield results, or show a ‘no results’ message if no results are found
Accessible props
The nested menu component gets its static and dynamic accessible props and attributes from a library it leverages under the hood (downshift, specifically the useSelect hook).
Roles
This component makes use of several roles:
listbox
This is used to identify an element that creates a list from which a user may select one or more static item.
<div
id="downshift-0-menu"
role="listbox"
aria-labelledby="downshift-0-label"
class="is-styled css-r6a1zw">combobox
This role identifies an element as an input that controls another element, such as a listbox. In the case of nested menu, the ‘trigger’ element is what controls our ‘listbox’.
<button
aria-activedescendant=""
aria-controls="downshift-0-menu"
aria-expanded="true"
aria-haspopup="listbox"
aria-labelledby="downshift-0-label"
id="downshift-0-toggle-button"
role="combobox"
tabindex="0"
class="icon-button is-styled css-10rjsc css-yyccrc">option
Used to identify selections a user can make in a listbox.
<li
aria-disabled="false"
aria-selected="false"
id="downshift-0-item-1"
role="option"
class="is-styled css-h3vdao"
></li>aria properties
aria-activedescendant
This attribute identifies the currently ‘active’ element, which is the highlighted, ‘navigated’ option.
aria-controls
This attribute is set on the element that ‘controls’ the contents, or ‘presence’ of the menu.
aria-expanded
This attribute is set on the trigger element, and automatically updated based on the ‘open’ state of the nested menu. When open, this attribute is set to ‘true’, when the menu closes, it gets set to false.
aria-haspopup
The aria-haspopupattribute helps screen readers determine if an element has a popup menu / dialog associated with it.
aria-labelledby
The aria-labelledby attribute associates the trigger element with the label through the labels id.
<button
aria-activedescendant="downshift-0-item-1"
aria-controls="downshift-0-menu"
aria-expanded="true"
aria-haspopup="listbox"
aria-labelledby="downshift-0-label"
id="downshift-0-toggle-button"
role="combobox"
tabindex="0"
class="icon-button is-styled css-10rjsc css-yyccrc">aria-selected
This attribute is set on the ‘option’, and automatically updates based on the ‘selected’ state of the nested menu. An option that has been ‘selected’ has the aria-selected attribute set to ‘true’.
<li
aria-disabled="false"
aria-selected="true"
id="downshift-0-item-1"
role="option"
class="is-styled css-h3vdao"
></li>