Skip to contentSkip to navigationSkip to topbar
Paste
FigmaStar

Sidebar

Sidebar contains navigation controls that rest on the left side of the screen.

Version 1.1.1
Github
Storybook

Installation

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

Usage

Usage page anchor
import {
  Sidebar,
  SidebarHeader,
  SidebarHeaderLabel,
  SidebarHeaderIconButton,
  SidebarCollapseButton,
  SidebarBody,
  SidebarFooter,
  SidebarPushContentWrapper,
  SidebarOverlayContentWrapper,
} from '@twilio-paste/core/sidebar';

const SideModalExample: React.FC = () => {
  const [pushSidebarCollapsed, setPushSidebarCollapsed] = React.useState(false);
  const sidebarNavigationSkipLinkID = useUID();
  const topbarSkipLinkID = useUID();
  const mainContentSkipLinkID = useUID();

  return (
    <Box>
      {/* Can be placed anywhere - position fixed */}
      <Sidebar
        sidebarNavigationSkipLinkID={sidebarNavigationSkipLinkID}
        topbarSkipLinkID={topbarSkipLinkID}
        mainContentSkipLinkID={mainContentSkipLinkID}
        collapsed={pushSidebarCollapsed}
        variant="default"
      >
        <SidebarHeader>
          <SidebarHeaderIconButton as="a" href="/">
            <ProductFlexIcon size="sizeIcon20" decorative={false} title="Go to Flex product homepage" />
          </SidebarHeaderIconButton>
          <SidebarHeaderLabel>Twilio Flex</SidebarHeaderLabel>
        </SidebarHeader>
        <SidebarBody>
          <SidebarBetaBadge as="span">Beta</SidebarBetaBadge>
        </SidebarBody>
        <SidebarFooter>
          <SidebarCollapseButton
            onClick={() => setPushSidebarCollapsed(!pushSidebarCollapsed)}
            i18nCollapseLabel="Close sidebar"
            i18nExpandLabel="Open sidebar"
          />
        </SidebarFooter>
      </Sidebar>

      {/* Must wrap content area */}
      <SidebarPushContentWrapper collapsed={pushSidebarCollapsed} variant="default">
        <main id={mainContentSkipLinkID}>
          <Button variant="primary" onClick={() => setPushSidebarCollapsed(!pushSidebarCollapsed)}>
            Toggle Push Sidebar
          </Button>
        </main>
      </SidebarPushContentWrapper>
    </Box>
  );
};

Props

Props page anchor
Sidebar page anchor

mainContentSkipLinkID RequiredRequired

ID of the element that contains the main content of your application

Type
string

sidebarNavigationSkipLinkID RequiredRequired

ID given to the SidebarNavigation component

Type
string

topbarSkipLinkID RequiredRequired

ID given to the Topbar component

Type
string

variant RequiredRequired

Whether the sidebar should hide completely or collapse into a fixed width bar.

Type
Variants

collapsed

Whether the sidebar is collapsed / closed.

Type
boolean

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR

i18nMainContentSkipLinkText

String used to change the text of the "skip to content" link

Type
string
Default
Skip to content

i18nNavigationSkipLinkText

String used to change the text of the "skip to navigation" link

Type
string
Default
Skip to navigation

i18nTopbarSkipLinkText

String used to change the text of the "skip to topbar" link

Type
string
Default
Skip to topbar

SidebarBody

SidebarBody page anchor

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_BODY

SidebarPushContentWrapper

SidebarPushContentWrapper page anchor

collapsed

Whether the sidebar is collapsed / closed.

Type
boolean

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_PUSH_CONTENT_WRAPPER

variant

Whether the sidebar should hide completely or collapse into a fixed width bar.

Type
Variants
Default
default

SidebarOverlayContentWrapper

SidebarOverlayContentWrapper page anchor

collapsed

Whether the sidebar is collapsed / closed.

Type
boolean

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_OVERLAY_CONTENT_WRAPPER

variant

Whether the sidebar should hide completely or collapse into a fixed width bar.

Type
Variants
Default
default

SidebarHeader

SidebarHeader page anchor

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_HEADER

SidebarHeaderLabel

SidebarHeaderLabel page anchor

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_HEADER_LABEL

SidebarHeaderIconButton

SidebarHeaderIconButton page anchor

as RequiredRequired

HTML element to render the button as.

Type
"a" | "button"

disabled

Prevent actions from firing on this Button

Type
boolean

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_HEADER_ICON_BUTTON

fullWidth

Sets the Button width to 100% of the parent container.

Type
boolean

href

The URL to navigate to if the button is rendered as an anchor element.

Type
string

loading

Prevent actions and show a loading spinner

Type
boolean

onClick

Callback function to handle the button's click event.

Type
MouseEventHandler<HTMLButtonElement>

tabIndex

Type
ButtonTabIndexes

target

Type
string

type

Use at least one submit button per <form>. Outside of forms use button (default).

Type
ButtonTypes
Default
'button'

SidebarFooter

SidebarFooter page anchor

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_FOOTER

SidebarCollapseButton

SidebarCollapseButton page anchor

i18nCollapseLabel RequiredRequired

A label for the collapse trigger for screenreader software.

Type
string

i18nExpandLabel RequiredRequired

A label for the expand trigger for screenreader software.

Type
string

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_COLLAPSE_BUTTON

onClick

Callback function to handle the click event

Type
() => void

SidebarNavigation

SidebarNavigation page anchor

aria-label RequiredRequired

Accessible name for the navigation element, useful for application navigation using assistive technology

Type
string

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_NAVIGATION

hideItemsOnCollapse

Set whether you would like the navigation item to hide when in a collapsed sidebar

Type
boolean

hierarchical

Set whether you are displaying an hierarchical navigation structure.

Type
boolean

SidebarNavigationDisclosureInitialState

SidebarNavigationDisclosureInitialState page anchor

SidebarNavigationDisclosureStateReturn

SidebarNavigationDisclosureStateReturn page anchor

animated RequiredRequired

If true, animating will be set to true when visible is updated. It'll wait for stopAnimation to be called or a CSS transition ends. If animated is set to a number, stopAnimation will be called only after the same number of milliseconds have passed.

Type
number | boolean

animating RequiredRequired

Whether it's animating or not.

Type
boolean

baseId RequiredRequired

ID that will serve as a base for all the items IDs.

Type
string

hide RequiredRequired

Changes the visible state to false

Type
() => void

setAnimated RequiredRequired

Sets animated.

Type
Dispatch<SetStateAction<number | boolean>>

setBaseId RequiredRequired

Sets baseId.

Type
Dispatch<SetStateAction<string>>

setVisible RequiredRequired

Sets visible.

Type
Dispatch<SetStateAction<boolean>>

show RequiredRequired

Changes the visible state to true

Type
() => void

stopAnimation RequiredRequired

Stops animation. It's called automatically if there's a CSS transition.

Type
() => void

toggle RequiredRequired

Toggles the visible state

Type
() => void

unstable_idCountRef RequiredRequired

Type
MutableRefObject<number>

visible RequiredRequired

Whether it's visible or not.

Type
boolean

SidebarNavigationDisclosureHeadingWrapper

SidebarNavigationDisclosureHeadingWrapper page anchor

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_NAVIGATION_DISCLOSURE_HEADING_WRAPPER

SidebarNavigationDisclosureHeading

SidebarNavigationDisclosureHeading page anchor

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_NAVIGATION_DISCLOSURE_HEADING

icon

Icon to be displayed within the Heading

Type
| string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | ReactFragment | ReactPortal

selected

Set to make the Heading part of the selected page hierarchy

Type
boolean

SidebarNavigationDisclosureContent

SidebarNavigationDisclosureContent page anchor

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_NAVIGATION_DISCLOSURE_CONTENT

SidebarNavigationItem

SidebarNavigationItem page anchor

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_NAVIGATION_ITEM

href

String for the url to link to.

Type
string

icon

Any product icons can be used here

Type
| string | number | boolean | ReactElement<any, string | JSXElementConstructor<any>> | ReactFragment | ReactPortal

selected

Set to indicate this item matches to the current page the user is on

Type
boolean

SidebarNavigationSeparator

SidebarNavigationSeparator page anchor

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
SIDEBAR_NAVIGATION_SEPARATOR

SidebarBetaBadge

SidebarBetaBadge page anchor

as RequiredRequired

The HTML element ro render the Badge as.

Type
"button" | "span"
Default
span

element

Overrides the default element name to apply unique styles with the Customization Provider

Type
string
Default
BADGE

href

Type
string