Drawer.md

Drawer

The <Drawer> component is side-menu that houses navigation items. The PX Blue Drawer includes helper components for <DrawerHeader>, <DrawerSubheader>, <DrawerBody>, <DrawerNavGroup>, <DrawerNavItem>, and <DrawerFooter>to help organize the content. To integrate in-app navigation, the <Drawer> component needs to be paired with a navigation provider — we recommend using React Navigation.

To learn more about the Navigation design pattern, check out our documentation.

Drawer

The <Drawer> component is the parent container, which manages the overall state of the drawer and renders the child components.

Drawer Usage

import { Drawer, DrawerHeader, DrawerBody, DrawerNavGroup, DrawerNavItem } from '@pxblue/react-native-components';

<Drawer
    activeItem={selectedItem}
    onItemSelect={(id) => {
        /* updateSelectedItem */
    }}
>
    <DrawerHeader title={'Drawer Title'} subtitle={'Drawer Subtitle'} icon={<Menu />} />
    <DrawerSubheader>{/* contents */}</DrawerSubheader>
    <DrawerBody>
        {/* Using 'items' prop */}
        <DrawerNavGroup
            title={'Navigation Group'}
            items={[
                {
                    title: 'Identity Management',
                    itemID: 'g1i1',
                },
            ]}
        />
        {/* Using children */}
        <DrawerNavGroup title={'Navigation Group'}>
            <DrawerNavItem itemID={'item1'} title={'Item 1'} />
            <DrawerNavItem itemID={'item2'} title={'Item 2'}>
                <DrawerNavItem itemID={'item3'} title={'Item 3'} />
            </DrawerNavItem>
        </DrawerNavGroup>
    </DrawerBody>
    <DrawerFooter>{/* contents */}</DrawerFooter>
</Drawer>;

Drawer API

Prop Name	Description	Type	Required	Default
activeItem	The itemID of the currently active / selected item	string	no
onItemSelect	A callback function to execute whenever a navigation item is clicked	(id: string) => void	no
...sharedProps	Props that can be set at any level in the drawer hierarchy	-	-

Any other props will be provided to the root element (Surface).

Styles

You can override the internal styles used by PX Blue by passing a styles prop. The Drawer supports the following keys:

Name	Description
root	Style override for the root Surface element

DrawerHeader

The <DrawerHeader> is a subsection that appears at the top of <Drawer>. Its content can be provided by the title, subtitle, and icon props, or you can pass in your own custom content via titleContent.

DrawerHeader API

Prop Name	Description	Type	Required	Default
backgroundColor	The color used for the background	string	no	theme.colors.primary
backgroundImage	An image to display in the header	ImageSourcePropType	no
backgroundOpacity	The opacity of the background image	number	no	0.3
fontColor	The color of the text elements	string	no	theme.colors.surface
icon	A component to render for the icon	IconSource	no
onIconPress	A callback to execute when the icon is pressed	() => void	no
subtitle	The second line of text	string	no
title	The first line of text	string	no
titleContent	Custom content for header title area	ReactNode	no
theme	Theme value overrides	$DeepPartial<ReactNativePaper.Theme>	no

Any other props will be provided to the root element (View).

Styles

You can override the internal styles used by PX Blue by passing a styles prop. The DrawerHeader supports the following keys:

Name	Description
root	Styles applied to the root element
backgroundImageWrapper	Styles applied to the background image wrapper
backgroundImage	Styles applied to the background image
content	Styles applied to the content wrapper
textContent	Styles applied to the text wrapper
title	Styles applied to the title element
subtitle	Styles applied to the subtitle element
icon	Styles applied to the left icon element

DrawerSubheader

The <DrawerSubheader> is an optional subsection that will appear below the <DrawerHeader> and above the <DrawerBody>. It can be used to support custom content (passed as children), such as filtering options or to display additional information.

DrawerSubheader API

Prop Name	Description	Type	Required	Default
divider	Whether to show a dividing line below the HeroBanner	boolean	no	true

DrawerBody

The <DrawerBody> is a wrapper for the main content of the Drawer. The typical use case is to display <DrawerNavGroup> elements, but custom elements (e.g., for spacing) are accepted as well.

DrawerBody API

Prop Name	Description	Type	Required	Default
styles	Style overrides	DrawerBodyStyles	no
...sharedProps	Props that can be set at any level in the drawer hierarchy	-	-

Any other props will be provided to the root element (ScrollView).

Styles

You can override the internal styles used by PX Blue by passing a styles prop. The Drawer supports the following keys:

Name	Description
root	Style override for the root ScrollView element

DrawerNavGroup

A <DrawerNavGroup> is used inside of the <DrawerBody> to organize links/content. Each group consists of an (optional) group title and a series of navigation items. Most visual props are inherited from the <DrawerBody> but can be overridden at the NavGroup level if desired.

The items property supports nested items to generate collapsible sections in the menu. This can be used to create an arbitrary tree depth, but we do not recommend going more than two levels deep in a navigation Drawer. You can also build the navigation links declaratively by passing <DrawerNavItem> children to the <DrawerNavGroup>.

DrawerNavGroup API

Prop Name	Description	Type	Required	Default
items	List of navigation items to render	NavItem[]	yes
title	Text to display in the group header	string	no
titleColor	Color used for the title text	string	no	varies for light/dark theme
titleContent	Custom element, substitute for title	ReactNode	no
...sharedProps	Props that can be set at any level in the drawer hierarchy	-	-

Any other props will be provided to the root element (View).

Styles

You can override the internal styles used by PX Blue by passing a styles prop. The DrawerNavGroup supports the following keys:

Name	Description
root	Styles applied to the root element
textContent	Styles applied to the text wrapper
title	Styles applied to the title element
divider	Styles applied to the divider elements

DrawerFooter

The <DrawerFooter> is an optional section that renders at the bottom of the <Drawer>. It can be used to add any custom content (as children).

DrawerFooter API

Prop Name	Description	Type	Required	Default
divider	Whether to show a dividing line above footer	boolean	no	true

DrawerNavItem

The <DrawerNavItem> is an individual line item in the <Drawer>. These can be generated for you by using the items prop of the <DrawerNavGroup> and passing in an array of objects with the following API. You can also create these line items by directly passing them as children to the <DrawerNavGroup>. Each <DrawerNavItem> also supports the ability to nest items (using its own items prop or children).

Drawer Nav Item API

Prop Name	Description	Type	Required	Default
depth*	The nested depth of the item	number	no	0
hidden	Hide / do not render the nav item	boolean	no	false
icon	A component to render for the left icon	IconSource	no
isInActiveTree*	Sets whether the item is a parent of the currently active item	boolean	no	false
itemID	An unique identifier of the NavItem. Item will have 'active' style when this matches activeItem	string	yes
items	The items nested under this item	NestedNavItem[]	no
notifyActiveParent*	Callback function to the parent element to update active hierarchy styles	(ids: string[]) => void	no
onPress	A function to execute when the item is pressed	() => void	no
rightComponent	Custom content/component to display to the right	ReactNode	no
statusColor	Color used for the status stripe and icon	string	no
subtitle	The text to show on the second line	string	no
title	The text to show on the first line	string	yes
...sharedProps	Props that can be set at any level in the drawer hierarchy	-	-

Props marked with a star (*) are managed automatically when using the <DrawerNavItem> inside of a <DrawerNavGroup>.

A <NestedNavItem> has all the same properties as a <NavItem> but does not support icons.

Styles

You can override the internal styles used by PX Blue by passing a styles prop. The DrawerNavItem supports the following keys:

Name	Description
root	Styles applied to the root element
activeBackground	Styles applied to the background of an active item
expandIcon	Styles applied to right content expand icon
infoListItem	Styles passed to the underlying InfoListItem

Shared Props

The following props can be set at any level in the drawer hierarchy (<Drawer>, <DrawerBody>, <DrawerNavGroup>, or <DrawerNavItem>). If they are set on a parent, they will be used for all children. For more customization, you can set these props on individual children and they will override any value set on the parent.

Name	Description	Type	Required	Default
activeItemBackgroundColor	Background color for the active item	string	no	varies for light/dark theme
activeItemBackgroundShape	Shape of the active item background highlight	'round' | 'square'	no	square
activeItemFontColor	Font color for the active item	string	no	varies for light/dark theme
activeItemIconColor	Icon color for the active item	string	no	varies for light/dark theme
backgroundColor	Color used for the background of the element	string	no
chevron	Add chevrons for all menu items	boolean	no	false
collapseIcon	Icon used to collapse a DrawerNavGroup	JSX.Element	no	expandIcon rotated 180 degrees
disableActiveItemParentStyles	When true, disables the semi-bold text style on parent elements of active item	boolean	no	false
divider	Show a dividing line between all items	boolean	no	false
expandIcon	Icon used to expand a DrawerNavGroup	JSX.Element	no	<MatIcon name={'expand-more'}/> at top-level, <MatIcon name={'arrow-drop-down'} /> for nested
hidePadding	Hide the padding reserved for DrawerNavItem icons	boolean	no
itemFontColor	The color used for the DrawerNavItem text	string	no	varies for light/dark theme
itemIconColor	The color used for the DrawerNavItem icon	string	no	varies for light/dark theme
nestedBackgroundColor	Background color for nested items	string	no	theme.palette.type === 'light' ? white[200] : darkBlack[100]
nestedDivider	Show a dividing line between nested items	boolean	no	false
theme	Theme value overrides	$DeepPartial<ReactNativePaper.Theme>	no