Drawer

The Drawer component provides a slide-in panel for navigation, forms, or supplementary content, appearing from the edge of the screen.

Installation

$ cbui-cli install @crossbuildui/drawer

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

MyComponent.tsx

import { Drawer } from '@/crossbuildui/drawer';
import type { DrawerPlacement, DrawerSize, DrawerRadius, DrawerBackdrop, DrawerAnimationConfig } from '@crossbuildui/drawer'; // Optional: for type safety
import { Button } from '@/crossbuildui/button'; // Or your preferred button component

Dependencies

The Drawer component uses expo-blur for the blur backdrop effect. Ensure it's installed if you plan to use this feature:
npm install expo-blur or yarn add expo-blur

It also relies on react-native-reanimated for animations. Make sure it's installed and configured.

Drawer Component

Basic Usage

Control the Drawer's visibility using the isOpen and onOpenChange props. Provide content as children.

MyComponent.tsx

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <View>
      <Button onPress={() => setIsOpen(true)}>Open Drawer</Button>
      <Drawer
        isOpen={isOpen}
        onOpenChange={setIsOpen}
        placement="left"
      >
        <View style={{ padding: 20, flex: 1 }}>
          <Text style={{ fontSize: 18, fontWeight: 'bold', marginBottom: 10 }}>Drawer Content</Text>
          <Text>This is the content of the drawer.</Text>
          <Button onPress={() => setIsOpen(false)} style={{ marginTop: 20 }}>
            Close Drawer
          </Button>
        </View>
      </Drawer>
    </View>
  );
}

Placement

The placement prop determines which edge the drawer slides in from: left (default), right, top, or bottom.

MyComponent.tsx

function App() {
  const [isOpen, setIsOpen] = useState(false);
  const [placement, setPlacement] = useState<DrawerPlacement>('left');

  const openDrawer = (p: DrawerPlacement) => {
    setPlacement(p);
    setIsOpen(true);
  };

  return (
    <View style={{ flexDirection: 'row', gap: 8, flexWrap: 'wrap' }}>
      <Button onPress={() => openDrawer('left')}>Open Left</Button>
      <Button onPress={() => openDrawer('right')}>Open Right</Button>
      <Button onPress={() => openDrawer('top')}>Open Top</Button>
      <Button onPress={() => openDrawer('bottom')}>Open Bottom</Button>

      <Drawer isOpen={isOpen} onOpenChange={setIsOpen} placement={placement}>
        <View style={{ padding: 20, flex: 1, alignItems: 'center', justifyContent: 'center' }}>
          <Text>Drawer from {placement}</Text>
          <Button onPress={() => setIsOpen(false)} style={{ marginTop: 10 }}>Close</Button>
        </View>
      </Drawer>
    </View>
  );
}

Sizes

Adjust the drawer's size (width for left/right, height for top/bottom) using the size prop. Options: sm, md (default), lg, full.

MyComponent.tsx

function App() {
  const [isOpen, setIsOpen] = useState(false);
  const [size, setSize] = useState<DrawerSize>('md');

  const openDrawer = (s: DrawerSize) => {
    setSize(s);
    setIsOpen(true);
  };

  return (
    <View style={{ flexDirection: 'row', gap: 8, flexWrap: 'wrap' }}>
      <Button onPress={() => openDrawer('sm')}>Small</Button>
      <Button onPress={() => openDrawer('md')}>Medium</Button>
      <Button onPress={() => openDrawer('lg')}>Large</Button>
      <Button onPress={() => openDrawer('full')}>Full</Button>

      <Drawer isOpen={isOpen} onOpenChange={setIsOpen} size={size} placement="left">
        <View style={{ padding: 20, flex: 1 }}>
          <Text>Drawer size: {size}</Text>
          <Button onPress={() => setIsOpen(false)} style={{ marginTop: 10 }}>Close</Button>
        </View>
      </Drawer>
    </View>
  );
}

Radius

Apply a border radius to the relevant corners of the drawer panel with the radius prop. Options: none, sm, md, lg (default).

MyComponent.tsx

function App() {
  const [isOpen, setIsOpen] = useState(false);
  const [radius, setRadius] = useState<DrawerRadius>('lg');

  const openDrawer = (r: DrawerRadius) => {
    setRadius(r);
    setIsOpen(true);
  };

  return (
    <View style={{ flexDirection: 'row', gap: 8, flexWrap: 'wrap' }}>
      <Button onPress={() => openDrawer('none')}>None</Button>
      <Button onPress={() => openDrawer('sm')}>Small</Button>
      <Button onPress={() => openDrawer('md')}>Medium</Button>
      <Button onPress={() => openDrawer('lg')}>Large</Button>

      <Drawer isOpen={isOpen} onOpenChange={setIsOpen} radius={radius} placement="right">
        <View style={{ padding: 20, flex: 1 }}>
          <Text>Drawer radius: {radius}</Text>
          <Button onPress={() => setIsOpen(false)} style={{ marginTop: 10 }}>Close</Button>
        </View>
      </Drawer>
    </View>
  );
}

Backdrop

Customize the backdrop using the backdrop prop: opaque (default, semi-transparent black), blur (requires expo-blur), or transparent.

MyComponent.tsx

function App() {
  const [isOpen, setIsOpen] = useState(false);
  const [backdrop, setBackdrop] = useState<DrawerBackdrop>('opaque');

  const openDrawer = (b: DrawerBackdrop) => {
    setBackdrop(b);
    setIsOpen(true);
  };

  return (
    <View style={{ flexDirection: 'row', gap: 8, flexWrap: 'wrap' }}>
      <Button onPress={() => openDrawer('opaque')}>Opaque</Button>
      <Button onPress={() => openDrawer('blur')}>Blur</Button>
      <Button onPress={() => openDrawer('transparent')}>Transparent</Button>

      <Drawer isOpen={isOpen} onOpenChange={setIsOpen} backdrop={backdrop}>
        <View style={{ padding: 20, flex: 1 }}>
          <Text>Backdrop: {backdrop}</Text>
          <Button onPress={() => setIsOpen(false)} style={{ marginTop: 10 }}>Close</Button>
        </View>
      </Drawer>
    </View>
  );
}

Dismissable Behavior

By default (isDismissable=), the drawer can be closed by pressing the backdrop or the hardware back button (Android). Set to false to prevent this.

MyComponent.tsx

function App() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <View>
      <Button onPress={() => setIsOpen(true)}>Open Non-Dismissable Drawer</Button>
      <Drawer
        isOpen={isOpen}
        onOpenChange={setIsOpen}
        isDismissable={false}
      >
        <View style={{ padding: 20, flex: 1 }}>
          <Text>This drawer cannot be dismissed by backdrop press or back button.</Text>
          <Button onPress={() => setIsOpen(false)} style={{ marginTop: 20 }}>
            Close Manually
          </Button>
        </View>
      </Drawer>
    </View>
  );
}

Animation Configuration

Customize the opening and closing animation using animationConfig. Supports type: 'spring' (default) or type: 'timing', with respective Reanimated configuration objects.

MyComponent.tsx

function App() {
  const [isOpenSpring, setIsOpenSpring] = useState(false);
  const [isOpenTiming, setIsOpenTiming] = useState(false);

  const springConfig: DrawerAnimationConfig = {
    type: 'spring',
    springConfig: { damping: 15, stiffness: 120 }
  };

  const timingConfig: DrawerAnimationConfig = {
    type: 'timing',
    timingConfig: { duration: 500 }
  };

  return (
    <View style={{ flexDirection: 'row', gap: 8 }}>
      <Button onPress={() => setIsOpenSpring(true)}>Open with Spring</Button>
      <Button onPress={() => setIsOpenTiming(true)}>Open with Timing</Button>

      <Drawer isOpen={isOpenSpring} onOpenChange={setIsOpenSpring} animationConfig={springConfig}>
        <View style={{ padding: 20, flex: 1 }}><Text>Spring Animation</Text><Button onPress={() => setIsOpenSpring(false)}>Close</Button></View>
      </Drawer>

      <Drawer isOpen={isOpenTiming} onOpenChange={setIsOpenTiming} animationConfig={timingConfig} placement="right">
        <View style={{ padding: 20, flex: 1 }}><Text>Timing Animation</Text><Button onPress={() => setIsOpenTiming(false)}>Close</Button></View>
      </Drawer>
    </View>
  );
}

Custom Close Button

The closeButton prop accepts a ReactNode for a custom close button. However, you are responsible for rendering this button within the drawer's children content at your desired location. The Drawer component itself does not automatically place it.

MyComponent.tsx

function App() {
  const [isOpen, setIsOpen] = useState(false);

  const MyCustomCloseButton = (
    <Button
      variant="ghost"
      size="sm"
      isIconOnly
      onPress={() => setIsOpen(false)}
      style={{ position: 'absolute', top: 10, right: 10, zIndex: 1 }}
    >
      <Text>X</Text> {/* Replace with an Icon component if available */}
    </Button>
  );

  return (
    <View>
      <Button onPress={() => setIsOpen(true)}>Open Drawer with Custom Close</Button>
      <Drawer
        isOpen={isOpen}
        onOpenChange={setIsOpen}
        closeButton={MyCustomCloseButton} // Prop provided, but user places it
      >
        <View style={{ padding: 20, flex: 1 }}>
          {/* User needs to render the closeButton where they want it */}
          {MyCustomCloseButton}
          <Text style={{ fontSize: 18, fontWeight: 'bold', marginTop: 40 }}>Drawer Title</Text>
          <Text>Content goes here...</Text>
        </View>
      </Drawer>
    </View>
  );
}

Props Overview

PROP	TYPE	DEFAULT	DESCRIPTION
`children`	`ReactNode`	-	Content of the drawer panel.
`size`	`DrawerSize`	`'md'`	Size of the drawer.
`radius`	`DrawerRadius`	`'lg'`	Border radius of the panel.
`placement`	`DrawerPlacement`	`'left'`	Edge from which drawer slides.
`isOpen`	`boolean`	-	Controlled open state.
`defaultOpen`	`boolean`	`false`	Initial open state (uncontrolled).
`isDismissable`	`boolean`	`true`	If dismissable by backdrop/back press.
`backdrop`	`DrawerBackdrop`	`'opaque'`	Backdrop type: transparent, opaque, blur.
`closeButton`	`ReactNode`	-	Custom close button element (user places it).
`animationConfig`	`DrawerAnimationConfig`	`{ type: 'spring' }`	Animation settings (spring/timing).
`styles`	`DrawerSlotsStyles`	-	Styles for slots (backdrop, panel).
`style`	`StyleProp<ViewStyle>`	-	Style for the main drawer panel.
`onOpenChange`	`(isOpen: boolean) => void`	-	Callback on open state change.
`onClose`	`() => void`	-	Callback when drawer closes.

Styling

Customize the Drawer's appearance using the style prop for the main panel or the styles prop for more granular control over internal slots.

The styles prop accepts an object with the following keys:

backdrop: Styles applied to the backdrop overlay View or BlurView.
panel: Styles applied to the main drawer panel Animated.View. These are merged with and can be overridden by the main style prop.

Style Precedence

The main style prop directly styles the drawer panel and will take precedence over styles defined in styles.panel for conflicting properties.

MyComponent.tsx

<Drawer
  isOpen={true} // Keep open for example
  onOpenChange={() => {}}
  placement="left"
  size="md"
  style={{ borderWidth: 2, borderColor: 'purple' }} // Styles the main panel
  styles={{
    backdrop: { backgroundColor: 'rgba(0, 255, 0, 0.2)' }, // Custom backdrop style
    panel: { shadowColor: 'blue', shadowOpacity: 0.8, elevation: 10 } // Additional panel styles
  }}
>
  <View style={{ padding: 20, flex: 1 }}>
    <Text>Styled Drawer</Text>
  </View>S
</Drawer>

Accessibility

The Drawer component is built on top of React Native's Modal, which handles some accessibility aspects like focus management.

The onRequestClose prop of the underlying RNModal is connected to handleClose, aiding in hardware back button dismissal on Android.
Ensure any interactive elements within the drawer, including a custom close button, are properly labeled for accessibility (e.g., using accessibilityLabel).
The content within the drawer should be structured semantically for screen readers.
Consider announcing the drawer's appearance or purpose to screen reader users if it's not immediately obvious from the context.

Skeleton Dropdown