Menu Primitive

An unstyled and accessible basis upon which to build Menus.

Status
beta
Version
0.1.7
Sources
Install
yarn add @twilio-paste/menu-primitive — or — yarn add @twilio-paste/core

Guidelines#

About Menu Primitive#

The menu primitive is an unstyled functional version of a menu. It can be used to build a component following the WAI-ARIA Menu pattern. Our Menu is built on top of this primitive.

The purpose of providing these unstyled primitives is to cater for instances when the styled Menu provided by Paste doesn’t meet the requirements needed to solve a unique or individual customer problem. At that point you are welcome to fallback to this functional primitive to roll your own styled menu while still providing a functional and accessible experience to your customers. However, we strongly recommend reviewing your design proposal with the Design Systems team before doing so.

This primitive should be used to compose all custom menus to ensure accessibility and upgrade paths.

Before you roll your own menus...

We strongly suggest that all components built on top of this primitive get reviewed by the Design Systems team and go through the UX Review process to ensure an excellent experience for our customers.

Examples#

Basic menu#

Custom styling#

You can provide custom styling to the primitive menu by utilizing the as prop on each component.

The menu primitive does not come with any styling, and thus you could mix the functionality of it with another component by using the as prop. By doing so, you can get styling from another component, and menu functionality from this primitive.

Because these are not styled, rendering any of them as another component you can mix the functionality of two components together. Styling from one, menu functionlity from the primitive component.

In the example below, we import the Paste Button import {Button} from '@twilio-paste/button'; and use it as the Menu Button via the as prop. We also use Box from Paste to style the menu and menu items.


Usage Guide#

This package is a wrapper around the Reakit Menu. If you’re wondering why we wrapped that package into our own, we reasoned that it would be best for our consumers’ developer experience. For example:

  • If we want to migrate the underlying nuts and bolts in the future, Twilio products that depend on this primitive would need to replace all occurrences of import … from ‘x-package’ to import … from ‘@some-new/package’. By wrapping it in @twilio-paste/x-primitive, this refactor can be avoided. The only change would be a version bump in the ‘package.json` file for the primitive.
  • We can more strictly enforce semver and backwards compatibility than some of our dependencies.
  • We can control when to provide an update and which versions we allow, to help reduce potential bugs our consumers may face.
  • We can control which APIs we expose. For example, we may chose to enable or disable usage of certain undocumented APIs.

We've chosen not to include MenuBar for now

Reakit includes a menubar which we are not exposing. The reason being is that a menubar is directly aligned to the desktop software menubar you see at the top of your screen. These have limited use cases on the web unless you're building a desktop replacement like Figma or Google Docs. We may reconsider this in the future if we see a good use for this.

API#

Installation#

yarn add @twilio-paste/menu-primitve - or - yarn add @twilio-paste/core

Props#

This props list is a scoped version of the properties available from the Reakit Menu package. For a full list, visit the Reakit.

useMenuPrimitiveState#
PropTypeDescriptionDefault
baseIdstringID that will serve as a base for all the items IDs.
rtlboolean
orientationhorizontal, vertical, undefined
currentIdstring, null, undefinedThe current focused item id.
loopboolean, horizontal, vertical
wrapboolean, horizontal, vertical
visiblebooleanWhether it's visible or not.
animatednumber, boolean
placementauto-start, auto, auto-end, top-start, top, top-end, right-start, right, right-end, bottom-end, bottom, bottom-start, left-end, left, left-start
gutternumber, undefinedOffset between the reference and the popover on the main axis. Should not be combined with unstable_offset.
PropTypeDescriptionDefault
hideOnClickOutsideboolean, undefinedWhen enabled, user can hide the dialog by clicking outside it.
disabledboolean, undefinedSame as the HTML attribute.
PropTypeDescriptionDefault
sizestring, number, undefined
PropTypeDescriptionDefault
disabledboolean, undefinedSame as the HTML attribute.
PropTypeDescriptionDefault
disabledboolean, undefinedSame as the HTML attribute.

No props to show

PropTypeDescriptionDefault
disabledboolean, undefinedSame as the HTML attribute.
idstring, undefinedSame as the HTML attribute.
onClick() => voidSame as the HTML attribute.
hrefstring, undefinedSame as the HTML attribute.
PropTypeDescriptionDefault
disabledboolean, undefinedSame as the HTML attribute.
valuestring, number, undefinedCheckbox's value is going to be used when multiple checkboxes share the same state. Checking a checkbox with value will add it to the state array.
checkedboolean, undefinedCheckbox's checked state. If present, it's used instead of state.
idstring, undefinedSame as the HTML attribute.
namestringMenuItemCheckbox's name as in menu.values.
PropTypeDescriptionDefault
disabledboolean, undefinedSame as the HTML attribute.
valuestring, number, undefinedCheckbox's value is going to be used when multiple checkboxes share the same state. Checking a checkbox with value will add it to the state array.
checkedboolean, undefinedCheckbox's checked state. If present, it's used instead of state.
idstring, undefinedSame as the HTML attribute.
namestringMenuItemRadio's name as in menu.values.

Support

If you need support, please open a new issue in our GitHub repository. Please try to provide as much detail as possible in your issue.

Contributing

The Paste design system is open source and contributions are welcome. Check out the project on GitHub to learn more about contributing.

Copyright © 2020 Twilio, Inc.