Skip to contentSkip to navigationSkip to topbar
Paste
FigmaStar

Status Menu

Peer review pending

A Status component communicates the status of a process or connectivity to an application or service.

Version 2.0.0
Github
Storybook
Component preview theme
const ProcessStatusMenu = () => {

  const [process, setProcess] = React.useState(ProcessObject.Success);

  const menu = useStatusMenuState();

  const onClick = (status) => {

    setProcess(ProcessObject[status]);

    menu.hide();

  };

  return (

    <>

      <StatusMenuBadge {...menu} i18nButtonLabel="Change account" variant={process.variant}>

        {process.children}

      </StatusMenuBadge>

      <StatusMenu {...menu} aria-label="Preferences">

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="success"

          checked={process.children === ProcessObject.Success.children}

          onClick={() => onClick('Success')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessSuccess">{ProcessObject.Success.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="neutral"

          checked={process.children === ProcessObject.Neutral.children}

          onClick={() => onClick('Neutral')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessNeutral">{ProcessObject.Neutral.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="warning"

          checked={process.children === ProcessObject.Warning.children}

          onClick={() => onClick('Warning')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessWarning">{ProcessObject.Warning.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="error"

          checked={process.children === ProcessObject.Error.children}

          onClick={() => onClick('Error')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessError">{ProcessObject.Error.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="InProgress"

          checked={process.children === ProcessObject.InProgress.children}

          onClick={() => onClick('InProgress')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessInProgress">{ProcessObject.InProgress.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="disabled"

          checked={process.children === ProcessObject.Disabled.children}

          onClick={() => onClick('Disabled')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessDisabled">{ProcessObject.Disabled.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="draft"

          checked={process.children === ProcessObject.Draft.children}

          onClick={() => onClick('Draft')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessDraft">{ProcessObject.Draft.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

      </StatusMenu>

    </>

  );

};



render(

  <ProcessStatusMenu />

)

Guidelines

Guidelines page anchor

About Status Menu

About Status Menu page anchor

Use a Status Menu to both display and change the status of a connection or process. It closely follows the Status Pattern and comes with preconfigured options for displaying the status of both processes and connections, using the correct icons for each.

Accessibility

Accessibility page anchor

Status Menu implements a Menu and supports all the same keyboard navigation that the Menu component does.

Examples

Examples page anchor

Process menu

Process menu page anchor

Use the process-related variants of Status Menu to display and interact with the status of a particular process.

Component preview theme
const ProcessStatusMenu = () => {

  const [process, setProcess] = React.useState(ProcessObject.Success);

  const menu = useStatusMenuState();

  const onClick = (status) => {

    setProcess(ProcessObject[status]);

    menu.hide();

  };

  return (

    <>

      <StatusMenuBadge {...menu} i18nButtonLabel="Change account" variant={process.variant}>

        {process.children}

      </StatusMenuBadge>

      <StatusMenu {...menu} aria-label="Preferences">

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="success"

          checked={process.children === ProcessObject.Success.children}

          onClick={() => onClick('Success')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessSuccess">{ProcessObject.Success.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="neutral"

          checked={process.children === ProcessObject.Neutral.children}

          onClick={() => onClick('Neutral')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessNeutral">{ProcessObject.Neutral.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="warning"

          checked={process.children === ProcessObject.Warning.children}

          onClick={() => onClick('Warning')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessWarning">{ProcessObject.Warning.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="error"

          checked={process.children === ProcessObject.Error.children}

          onClick={() => onClick('Error')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessError">{ProcessObject.Error.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="InProgress"

          checked={process.children === ProcessObject.InProgress.children}

          onClick={() => onClick('InProgress')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessInProgress">{ProcessObject.InProgress.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="disabled"

          checked={process.children === ProcessObject.Disabled.children}

          onClick={() => onClick('Disabled')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessDisabled">{ProcessObject.Disabled.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          {...menu}

          name="process"

          value="draft"

          checked={process.children === ProcessObject.Draft.children}

          onClick={() => onClick('Draft')}

          variant="default"

        >

          <StatusMenuItemChild variant="ProcessDraft">{ProcessObject.Draft.children}</StatusMenuItemChild>

        </StatusMenuItemRadio>

      </StatusMenu>

    </>

  );

};



render(

  <ProcessStatusMenu />

)

Connectivity Menu

Connectivity Menu page anchor

Use the connectivity-related variants of Status Menu to display and interact with the status of a particular connection.

Component preview theme
const ConnectivityStatusMenu = () => {

  const [availability, setConnectivity] = React.useState(ConnectivityObject.Available);

  const menu = useStatusMenuState();

  const onClick = (status) => {

    setConnectivity(ConnectivityObject[status]);

    menu.hide();

  };

  return (

    <>

      <StatusMenuBadge {...menu} i18nButtonLabel="Change account" variant={availability.variant}>

        {availability.children}

      </StatusMenuBadge>

      <StatusMenu {...menu} aria-label="Preferences">

        <StatusMenuItemRadio

          name="availability"

          checked={availability.children === 'Available'}

          value="available"

          {...menu}

          onClick={() => onClick('Available')}

          variant="default"

        >

          <StatusMenuItemChild variant="ConnectivityAvailable">Available</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          name="availability"

          checked={availability.children === 'Busy'}

          value="busy"

          {...menu}

          onClick={() => onClick('Busy')}

          variant="default"

        >

          <StatusMenuItemChild variant="ConnectivityBusy">Busy</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          name="availability"

          checked={availability.children === 'Unavailable'}

          value="unavailable"

          {...menu}

          onClick={() => onClick('Unavailable')}

          variant="default"

        >

          <StatusMenuItemChild variant="ConnectivityUnavailable">Unavailable</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          name="availability"

          checked={availability.children === 'Neutral'}

          value="neutral"

          {...menu}

          onClick={() => onClick('Neutral')}

          variant="default"

        >

          <StatusMenuItemChild variant="ConnectivityNeutral">Neutral</StatusMenuItemChild>

        </StatusMenuItemRadio>

        <StatusMenuItemRadio

          name="availability"

          checked={availability.children === 'Offline'}

          value="offline"

          {...menu}

          onClick={() => onClick('Offline')}

          variant="default"

        >

          <StatusMenuItemChild variant="ConnectivityOffline">Offline</StatusMenuItemChild>

        </StatusMenuItemRadio>

      </Menu>

    </>

  );

};



render(

  <ConnectivityStatusMenu />

)

Composition notes

Composition notes page anchor

Status Menu consists of StatusMenu, StatusMenuBadge, StatusMenuItem, StatusMenuItemRadio, StatusMenuItemCheckbox, and useStatusMenuState. These are all namesakes of their Menu equivalents and follow the same API. It also comes with one additional component called StatusMenuItemChild.

Status Menu Item Child

Status Menu Item Child page anchor

StatusMenuItemChild is where the status pattern is implemented. It takes a variant prop that is set to a value that directly relates to one of the connectivity or process status types. It pairs the correct icon with its color implementation for the status. Check out the full list of variant options in the props table.

Usage Guide

Usage Guide page anchor

API

API page anchor

Installation

Installation page anchor
yarn add @twilio-paste/Status - or - yarn add @twilio-paste/core

Usage

Usage page anchor
import {
  StatusMenu,
  StatusMenuBadge,
  StatusMenuItem,
  StatusMenuItemChild,
  useStatusMenuState,
  StatusMenuItemRadio,
  StatusMenuItemCheckbox,
} from '@twilio-paste/core/status';

const ProcessStatusMenu = () => {
  const [process, setProcess] = React.useState(ProcessObject.Success);
  const menu = useStatusMenuState();
  const onClick = (status) => {
    setProcess(ProcessObject[status]);
    menu.hide();
  };
  return (
    <>
      <StatusMenuBadge {...menu} i18nButtonLabel="Change account" variant={process.variant}>
        {process.children}
      </StatusMenuBadge>
      <StatusMenu {...menu} aria-label="Preferences">
        <StatusMenuItem {...menu} onClick={() => onClick('Success')} variant="default">
          <StatusMenuItemChild variant="ProcessSuccess">Complete</StatusMenuItemChild>
        </StatusMenuItem>
        <StatusMenuItem {...menu} onClick={() => onClick('Neutral')} variant="default">
          <StatusMenuItemChild variant="ProcessNeutral">In review</StatusMenuItemChild>
        </StatusMenuItem>
        <StatusMenuItem {...menu} onClick={() => onClick('Warning')} variant="default">
          <StatusMenuItemChild variant="ProcessWarning">Needs attention</StatusMenuItemChild>
        </StatusMenuItem>
        <StatusMenuItem {...menu} onClick={() => onClick('Error')} variant="default">
          <StatusMenuItemChild variant="ProcessError">Rejected</StatusMenuItemChild>
        </StatusMenuItem>
        <StatusMenuItem {...menu} onClick={() => onClick('InProgress')} variant="default">
          <StatusMenuItemChild variant="ProcessInProgress">In-progress</StatusMenuItemChild>
        </StatusMenuItem>
        <StatusMenuItem {...menu} onClick={() => onClick('Disabled')} variant="default">
          <StatusMenuItemChild variant="ProcessDisabled">Paused</StatusMenuItemChild>
        </StatusMenuItem>
        <StatusMenuItem {...menu} onClick={() => onClick('Draft')} variant="default">
          <StatusMenuItemChild variant="ProcessDraft">Draft</StatusMenuItemChild>
        </StatusMenuItem>
      </Menu>
    </>
  );
};

Props

Props page anchor
useStatusMenuState
useStatusMenuState page anchor

Pass these as part of an object to the useStatusMenuState hook.

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.
useStatusMenuState returned props
useStatusMenuState returned props page anchor

These props are returned by the state hook. You can spread them into this component ({...state}) or pass them separately. You can also provide these props from your own state logic.

PropTypeDescriptionDefault
baseIdstringID that will serve as a base for all the items IDs.
baseIdstringID that will serve as a base for all the items IDs.
visiblebooleanWhether it's visible or not.
animatednumber | boolean
modalbooleanToggles Dialog's modal state.
animatingbooleanWhether it's animating or not.
stopAnimation() => voidStops animation. It's called automatically if there's a CSS transition.
hide() => voidChanges the visible state to false
placement"auto-start" | "auto" | "auto-end" | "top-start...Actual placement.
orientation"horizontal" | "vertical" | undefinedDefines the orientation of the composite widget.
currentIdstring | null | undefinedThe current focused item id.
wrapboolean | "horizontal" | "vertical"If enabled, moving to the next item from the last one in a row or column will focus the first item in the next row or column and vice-versa.
groupsGroup[]Lists all the composite groups with their id and DOM ref.
itemsItem[]Lists all the composite items with their id, DOM ref, disabled state and groupId if any.
setCurrentId(value: SetStateAction<string | null | undefine...Sets currentId.
first() => voidMoves focus to the first item.
last() => voidMoves focus to the last item.
move(id: string | null) => voidMoves focus to a given item ID.
next(unstable_allTheWay?: boolean | undefined) => voidMoves focus to the next item.
previous(unstable_allTheWay?: boolean | undefined) => voidMoves focus to the previous item.
StatusMenu
StatusMenu page anchor
PropTypeDescriptionDefault
hideOnClickOutsideboolean, undefinedWhen enabled, user can hide the dialog by clicking outside it.
disabledboolean, undefinedSame as the HTML attribute.
element?stringOverrides the default element name to apply unique styles with the Customization Provider'MENU'
StatusMenuBadge
StatusMenuBadge page anchor
PropTypeDescriptionDefault
as?stringThe HTML tag to replace the default <button> tag.'button'
disabled?booleanPrevent actions from firing on this Buttonfalse
fullWidthbooleanSets the Button width to 100% of the parent container.false
href?stringA URL to route to. Must use as="a" for this prop to work.null
loading?booleanPrevent actions and show a loading spinnerfalse
size?ButtonSizes'default', 'small', 'icon', 'icon_small', 'reset', 'rounded_small''default'
type?ButtonTypes'button', 'submit', 'reset'. If the Button is inside a <form>: use 'submit'. Otherwise use 'button' (default).'button'
variantStatusBadgeVariantsProcessError, ProcessWarning, ProcessSuccess, ProcessNeutral, ProcessInProgress, ProcessDisabled, ProcessDraft, AvailabilityAvailable, AvailabilityBusy, AvailabilityUnavailable, AvailabilityNeutral, AvailabilityOfflinenull
i18nExternalLinkLabel?stringTitle for showExternal icon'(link takes you to an external page)'
pressed?booleanSets the aria-pressed attribute. Must be used with 'secondary' or 'secondary_icon' variants.
onClick?(event: React.MouseEvent<HTMLElement>)null
onMouseDown?(event: React.MouseEvent<HTMLElement>)null
onMouseUp?(event: React.MouseEvent<HTMLElement>)null
onMouseEnter?(event: React.MouseEvent<HTMLElement>)null
onMouseLeave?(event: React.MouseEvent<HTMLElement>)null
onFocus?(event: React.FocusEvent<HTMLElement>)null
onBlur?(event: React.FocusEvent<HTMLElement>)null
element?stringOverrides the default element name to apply unique styles with the Customization Provider'STATUS_MENU_BADGE'
StatusMenuItem
StatusMenuItem page anchor
PropTypeDescriptionDefault
variantMenuItemVariantsSwaps the menu item variant. Options are default and destructive.default
disabledboolean, undefinedSame as the HTML attribute.
idstring, undefinedSame as the HTML attribute.
onClick() => voidSame as the HTML attribute.
hrefstring, undefinedSame as the HTML attribute.
element?stringOverrides the default element name to apply unique styles with the Customization Provider'MENU_ITEM'
StatusMenuItemCheckbox
StatusMenuItemCheckbox page anchor
PropTypeDescriptionDefault
variantMenuItemVariantsSwaps the menu item variant. Options are default and destructive.default
disabledboolean, undefinedSame as the HTML attribute.
idstring, undefinedSame as the HTML attribute.
onClick() => voidSame as the HTML attribute.
hrefstring, undefinedSame as the HTML attribute.
element?stringOverrides the default element name to apply unique styles with the Customization Provider'MENU_ITEM'
value?string
checked?boolean
name?string
StatusMenuItemRadio
StatusMenuItemRadio page anchor
PropTypeDescriptionDefault
variantMenuItemVariantsSwaps the menu item variant. Options are default and destructive.default
disabledboolean, undefinedSame as the HTML attribute.
idstring, undefinedSame as the HTML attribute.
onClick() => voidSame as the HTML attribute.
hrefstring, undefinedSame as the HTML attribute.
element?stringOverrides the default element name to apply unique styles with the Customization Provider'MENU_ITEM'
value?string
checked?boolean
name?string
StatusMenuItemChild
StatusMenuItemChild page anchor
PropTypeDescriptionDefault
variantStatusBadgeVariantsSwaps the menu item variant. Options are ProcessError, ProcessWarning, ProcessSuccess, ProcessNeutral, ProcessInProgress, ProcessDisabled, ProcessDraft, ConnectivityAvailable, ConnectivityBusy, ConnectivityUnavailable, ConnectivityOffline, ConnectivityNeutral.
element?stringOverrides the default element name to apply unique styles with the Customization Provider'MENU_ITEM_STATUS'