Overview
The controlDrawerNavigator action targets the app-level Drawer Navigator — the slide-out navigation shell configured in App Settings → Navigation → Drawer. This is distinct from the controlDrawer action, which targets content-level Drawer blocks placed on individual pages.
| Feature | controlDrawerNavigator | controlDrawer |
| Target | App-level navigation drawer shell | A Drawer content block on a page |
| Scope | Global — persists across page navigations | Page-local — torn down when page unmounts |
| Contains | App navigation links, user profile, branding | Arbitrary page content (filters, forms, details) |
| Configured in | App Settings → Navigation | Page Builder canvas |
Parameters
| Parameter | Type | Required | Default | Description |
| operation | "open" | "close" | "toggle" | Required (required) | — | open slides the drawer into view. close dismisses it. toggle opens it if currently closed, closes it if currently open — ideal for a hamburger button that should both open and dismiss the drawer. |
| drawerRef | string | Optional (optional) | — | When the app has multiple named drawer navigators (e.g. a left drawer and a right contextual drawer), specify the drawer name here. Omit to target the default (primary) drawer navigator. Named drawers are defined in App Settings → Navigation → Drawers. |
Note: Mobile gesture support: On mobile, the Drawer Navigator can also be opened by a swipe-from-edge gesture (if enabled in navigation settings). The controlDrawerNavigator action works alongside gesture control — calling open when the drawer is already open (from a gesture) is a no-op.
Step-by-Step Usage Guide
Enable Drawer Navigator in App Settings: Go to App Settings → Navigation → Navigation Type and select Drawer. Configure your navigation items, header, and footer content. The drawer is now available at the app shell level.
Add a hamburger button to your header: In the page header bar (or App Header component), add an Icon Button with a hamburger or menu icon. This button will be the primary entry point for opening the navigation drawer.
Wire the onClick event: In the button's onClick event, add a Control Drawer Navigator action. Set
operationto"toggle". This single action handles both open and close, making the button act as a true toggle.Auto-close on navigation (optional): To close the drawer automatically when the user taps a navigation link inside it, add a Control Drawer Navigator action with
operation: "close"to the onNavigate event of each navigation item inside the drawer.
Best Practices
Use
togglefor hamburger buttons — it eliminates the need for a condition checking the current drawer state.Close on backdrop tap — the Drawer Navigator closes when the user taps the dimmed backdrop by default. Do not fight this by re-opening in the backdrop's event handler.
Accessibility — pair the hamburger button with
aria-label="Open navigation menu"and ensure focus is moved into the drawer when opened. UnifyApps handles focus trapping automatically when the drawer is open.Avoid opening programmatically on page load — auto-opening the drawer on
onPageLoadis disorienting for returning users. Reserve it for intentional interactions.
Examples
Toggle the navigation drawer from a hamburger button
{ "actionType": "controlDrawerNavigator", "payload": { "operation": "toggle" } }
Close a named secondary drawer
{ "actionType": "controlDrawerNavigator", "payload": { "operation": "close", "drawerRef": "rightContextualDrawer" } }
Open the drawer and navigate — two sequential actions
// Step 1: Open the nav drawer { "actionType": "controlDrawerNavigator", "payload": { "operation": "open" } } // Step 2: Scroll a specific nav item into view (for long menus) { "actionType": "controlBlockMethod", "payload": { "blockId": "b_settingsNavItem", "methodName": "scrollIntoView" } }