Drawer

A drawer is a panel that slides in from the left side of the screen.

Caution

We are planning on deprecating Drawer. Please use Modal instead. Drawer should not be used with our new Navigation system

Examples Code Usage Migration guide Changelog

Migration guide

The latest version of @atlaskit/drawer has been migrated from Emotion to Compiled CSS-in-JS. As part of this migration, we have moved to a compositional API. This new compositional API will replace @atlaskit/drawer in a future major version, but for now it's opt-in.

Using the new compositional API

The new components are available via the @atlaskit/drawer entry point. There are three new sub-components available:

DrawerContent: Place the main content of the drawer inside this component.
DrawerSidebar: The sidebar sits next to the main content and is designed to contain the close button.
DrawerCloseButton: An icon button that closes the drawer.

Example migration diff

-import Drawer from '@atlaskit/drawer';
+import { Drawer, DrawerContent, DrawerCloseButton } from '@atlaskit/drawer';

export default MyDrawer = () => (
   <Drawer>
-    Hello world
+    <DrawerSidebar>
+      <DrawerCloseButton />
+    </DrawerSidebar>
+    <DrawerContent>Hello world</DrawerContent>
   </Drawer>
);

Basic usage

The default form of a drawer using the new compositional API.

import React, { useState } from 'react';

import Button from '@atlaskit/button/default/button';
import { Drawer } from '@atlaskit/drawer/drawer';
import { DrawerCloseButton } from '@atlaskit/drawer/drawer-close-button';
import { DrawerContent } from '@atlaskit/drawer/drawer-content';
import { DrawerSidebar } from '@atlaskit/drawer/drawer-sidebar';

import { Lorem } from '../lorem';

const DrawerDefaultExample = (): React.JSX.Element => {
	const [open, setOpen] = useState<boolean>(false);

	return (
		<>
			<Drawer label="Default drawer" onClose={() => setOpen(false)} isOpen={open}>
				<DrawerSidebar>
					<DrawerCloseButton />
				</DrawerSidebar>
				<DrawerContent>
					<Lorem count={10} />
				</DrawerContent>
			</Drawer>
			<Button appearance="primary" onClick={() => setOpen(true)}>
				Open drawer
			</Button>
		</>
	);
};

export default DrawerDefaultExample;

Customization

Previously, customizing the drawer UI was handled via the overrides prop, which has now been removed. Customization is now achieved via composition and the xcss prop.

Migrating `overrides.[sidebar|content].cssFn` prop

The legacy API allowed you to specify style overrides for the drawer sidebar and drawer content via cssFn props. Safe style overrides can now be applied via xcss props on the DrawerContent and DrawerSidebar components.

import React, { useState } from 'react';

import Button from '@atlaskit/button/default/button';
import { cssMap, jsx } from '@atlaskit/css';
import { Drawer } from '@atlaskit/drawer/drawer';
import { DrawerCloseButton } from '@atlaskit/drawer/drawer-close-button';
import { DrawerContent } from '@atlaskit/drawer/drawer-content';
import { DrawerSidebar } from '@atlaskit/drawer/drawer-sidebar';
import { token } from '@atlaskit/tokens';

import { Lorem } from '../lorem';

const styles = cssMap({
	sidebar: {
		backgroundColor: token('color.background.accent.gray.subtlest'),
	},
	content: {
		marginBlockStart: token('space.0'),
		paddingInlineStart: token('space.300'),
		paddingInlineEnd: token('space.300'),
		paddingBlockStart: token('space.300'),
		paddingBlockEnd: token('space.300'),
	},
});

export default function DrawerExample(): JSX.Element {
	const [isDrawerOpen, setIsDrawerOpen] = useState(false);

	return (
		<React.Fragment>
			<Drawer isOpen={isDrawerOpen} label="Drawer with xcss" onClose={() => setIsDrawerOpen(false)}>
				<DrawerSidebar xcss={styles.sidebar}>
					<DrawerCloseButton />
				</DrawerSidebar>
				<DrawerContent xcss={styles.content}>
					<Lorem count={10} />
				</DrawerContent>
			</Drawer>
			<Button appearance="primary" onClick={() => setIsDrawerOpen(true)}>
				Open drawer
			</Button>
		</React.Fragment>
	);
}

Migrating `overrides.[sidebar|content].component` prop

The legacy API allowed you to override the sidebar and content components, although it wasn’t recommended. Utilizing composition is the recommended migration path.

Below is an example of this; the Drawer components are composed with other elements/components to produce a centered layout without a sidebar.

import React, { useState } from 'react';

import Button from '@atlaskit/button/default/button';
import { cssMap, jsx } from '@atlaskit/css';
import { Drawer } from '@atlaskit/drawer/drawer';
import { DrawerCloseButton } from '@atlaskit/drawer/drawer-close-button';
import { DrawerContent } from '@atlaskit/drawer/drawer-content';
import { Stack } from '@atlaskit/primitives/compiled/stack';
import { Text } from '@atlaskit/primitives/compiled/text';
import { token } from '@atlaskit/tokens';

import { Lorem } from '../lorem';

const styles = cssMap({
	buttonLayout: {
		position: 'absolute',
		insetBlockStart: token('space.200'),
		insetInlineStart: token('space.200'),
	},
	content: {
		marginBlockStart: token('space.0'),
		paddingInlineStart: token('space.300'),
		paddingInlineEnd: token('space.300'),
	},
	contentLayout: {
		height: '100%',
		display: 'flex',
		alignItems: 'center',
		textAlign: 'center',
	},
});

export default function DrawerExample(): JSX.Element {
	const [isDrawerOpen, setIsDrawerOpen] = useState(false);

	return (
		<React.Fragment>
			<Drawer
				isOpen={isDrawerOpen}
				label="Drawer with customized composition"
				onClose={() => setIsDrawerOpen(false)}
			>
				<div css={styles.buttonLayout}>
					<DrawerCloseButton />
				</div>
				<DrawerContent xcss={styles.content}>
					<div css={styles.contentLayout}>
						<Stack space="space.200" alignInline="center">
							<Text size="large" weight="bold">
								Centered content
							</Text>
							<Lorem count={1} />
							<Button onClick={() => setIsDrawerOpen(false)}>Close</Button>
						</Stack>
					</div>
				</DrawerContent>
			</Drawer>
			<Button appearance="primary" onClick={() => setIsDrawerOpen(true)}>
				Open drawer
			</Button>
		</React.Fragment>
	);
}

List of prop changes

With the compositional API, some props that were previously available on the Drawer component have now been relocated to the sub-component that utilizes the value. Making it clearer which underlying element the prop relates to.

Legacy Drawer Prop	Change in new API
`icon`	Moved to: `icon` prop on `DrawerCloseButton`
`closeLabel`	Moved to: `label` prop on `DrawerCloseButton`
`scrollContentLabel`	Moved to: `scrollContentLabel` prop on `DrawerContent`
`overrides`	Removed: Use `xcss` prop on `DrawerContent`/`DrawerSidebar` and/or composition.

Was this page helpful?

We use this feedback to improve our documentation.