14.0.0 • Published 5 months ago

@material/drawer v14.0.0

Weekly downloads
38,160
License
MIT
Repository
github
Last release
5 months ago

Drawers

The MDC Drawer component is a spec-aligned drawer component adhering to the Material Design navigation drawer pattern. It implements permanent, persistent, and temporary drawers. Permanent drawers are CSS-only and require no JavaScript, whereas persistent and temporary drawers require JavaScript to function, in order to respond to user interaction.

Design & API Documentation

Installation

npm install @material/drawer

Permanent drawer usage

A permanent drawer is always open, sitting to the side of the content. It is appropriate for any display size larger than mobile.

TODO(sgomes): Give advice on how to hide permanent drawer in mobile.

<nav class="mdc-drawer mdc-drawer--permanent mdc-typography">
  <div class="mdc-drawer__toolbar-spacer"></div>
  <div class="mdc-drawer__content">
    <nav id="icon-with-text-demo" class="mdc-list">
      <a class="mdc-list-item mdc-list-item--activated" href="#">
        <i class="material-icons mdc-list-item__graphic" aria-hidden="true">inbox</i>Inbox
      </a>
      <a class="mdc-list-item" href="#">
        <i class="material-icons mdc-list-item__graphic" aria-hidden="true">star</i>Star
      </a>
    </nav>
  </div>
</nav>
<div>
  Toolbar and page content go inside here.
</div>

In the example above, we've set the drawer above the toolbar, and are using a toolbar spacer to ensure that it is presented correctly, with the correct amount of space to match the toolbar height. Note that you can place content inside the toolbar spacer.

Permanent drawers can also be set below the toolbar:

<div>Toolbar goes here</div>

<div class="content">
  <nav class="mdc-drawer mdc-drawer--permanent mdc-typography">
    <nav id="icon-with-text-demo" class="mdc-list">
      <a class="mdc-list-item mdc-list-item--activated" href="#">
        <i class="material-icons mdc-list-item__graphic" aria-hidden="true">inbox</i>Inbox
      </a>
      <a class="mdc-list-item" href="#">
        <i class="material-icons mdc-list-item__graphic" aria-hidden="true">star</i>Star
      </a>
    </nav>
  </nav>
  <main>
    Page content goes here.
  </main>
</div>

CSS classes:

ClassDescription
mdc-drawerMandatory. Needs to be set on the root element of the component.
mdc-drawer--permanentMandatory. Needs to be set on the root element of the component.
mdc-drawer__toolbar-spacerOptional. Add to node to provide the matching amount of space for toolbar.

Persistent drawer usage

Persistent drawers can be toggled open or closed. The drawer sits on the same surface elevation as the content. It is closed by default. When the drawer is outside of the page grid and opens, the drawer forces other content to change size and adapt to the smaller viewport. Persistent drawers stay open until closed by the user.

Persistent drawers are acceptable for all sizes larger than mobile.

<aside class="mdc-drawer mdc-drawer--persistent mdc-typography">
  <nav class="mdc-drawer__drawer">
    <header class="mdc-drawer__header">
      <div class="mdc-drawer__header-content">
        Header here
      </div>
    </header>
    <nav id="icon-with-text-demo" class="mdc-drawer__content mdc-list">
      <a class="mdc-list-item mdc-list-item--activated" href="#">
        <i class="material-icons mdc-list-item__graphic" aria-hidden="true">inbox</i>Inbox
      </a>
      <a class="mdc-list-item" href="#">
        <i class="material-icons mdc-list-item__graphic" aria-hidden="true">star</i>Star
      </a>
    </nav>
  </nav>
</aside>
let drawer = new mdc.drawer.MDCPersistentDrawer(document.querySelector('.mdc-drawer--persistent'));
document.querySelector('.menu').addEventListener('click', () => drawer.open = true);

CSS classes:

ClassDescription
mdc-drawerMandatory. Needs to be set on the root element of the component.
mdc-drawer--persistentMandatory. Needs to be set on the root element of the component.
mdc-drawer__drawerMandatory. Needs to be set on the container node for the drawer content.

Sass Mixins

To customize the fill color, the ink color, or scrim color (transparent mask found in the temporary drawer), you can use the following mixins.

mdc-drawer-fill-color($color)

This mixin customizes the fill (background) color of the drawer.

mdc-drawer-ink-color($color)

This mixin customizes the ink color (font / copy color) of the drawer.

mdc-drawer-fill-color-accessible($color)

This mixin customizes the fill color of the drawer. It also sets the ink color to an accessible complement of the fill.

mdc-drawer-scrim-color($color, $opacity)

This mixin customizes the color and opacity of the scrim. (temporary drawer only)

Using the JS Component

MDC Persistent Drawer ships with a Component / Foundation combo which allows for frameworks to richly integrate the correct drawer behaviors into idiomatic components.

Including in code

ES2015
import {MDCPersistentDrawer, MDCPersistentDrawerFoundation, util} from '@material/drawer';
CommonJS
const mdcDrawer = require('mdc-drawer');
const MDCPersistentDrawer = mdcDrawer.MDCPersistentDrawer;
const MDCPersistentDrawerFoundation = mdcDrawer.MDCPersistentDrawerFoundation;
const util = mdcDrawer.util;
AMD
require(['path/to/mdc-drawer'], mdcDrawer => {
  const MDCPersistentDrawer = mdcDrawer.MDCPersistentDrawer;
  const MDCPersistentDrawerFoundation = mdcDrawer.MDCPersistentDrawerFoundation;
  const util = mdcDrawer.util;
});
Global
const MDCPersistentDrawer = mdc.drawer.MDCPersistentDrawer;
const MDCPersistentDrawerFoundation = mdc.drawer.MDCPersistentDrawerFoundation;
const util = mdc.drawer.util;

Automatic Instantiation

If you do not care about retaining the component instance for the persistent drawer, simply call attachTo() and pass it a DOM element.

mdc.drawer.MDCPersistentDrawer.attachTo(document.querySelector('.mdc-drawer--persistent'));

Manual Instantiation

Persistent drawers can easily be initialized using their default constructors as well, similar to attachTo.

import {MDCPersistentDrawer} from '@material/drawer';

const drawer = new MDCPersistentDrawer(document.querySelector('.mdc-drawer--persistent'));

Handling events

When the drawer is opened or closed, the component will emit a MDCPersistentDrawer:open or MDCPersistentDrawer:close custom event with no data attached. Events get emitted only when the drawer toggles its opened state, i.e. multiple consecutive drawer.open = true calls will result in only one MDCPersistentDrawer:open.

Using the Foundation Class

MDC Persistent Drawer ships with an MDCPersistentDrawerFoundation class that external frameworks and libraries can use to integrate the component. As with all foundation classes, an adapter object must be provided. The adapter for persistent drawers must provide the following functions, with correct signatures:

Method SignatureDescription
addClass(className: string) => voidAdds a class to the root element.
removeClass(className: string) => voidRemoves a class from the root element.
hasClass(className: string) => booleanReturns boolean indicating whether element has a given class.
hasNecessaryDom() => booleanReturns boolean indicating whether the necessary DOM is present (namely, the mdc-drawer__drawer drawer container).
registerInteractionHandler(evt: string, handler: EventListener) => voidAdds an event listener to the root element, for the specified event name.
deregisterInteractionHandler(evt: string, handler: EventListener) => voidRemoves an event listener from the root element, for the specified event name.
registerDrawerInteractionHandler(evt: string, handler: EventListener) => voidAdds an event listener to the drawer container sub-element, for the specified event name.
deregisterDrawerInteractionHandler(evt: string, handler: EventListener) => voidRemoves an event listener from drawer container sub-element, for the specified event name.
registerTransitionEndHandler(handler: EventListener) => voidRegisters an event handler to be called when a transitionend event is triggered on the drawer container sub-element element.
deregisterTransitionEndHandler(handler: EventListener) => voidDeregisters an event handler from a transitionend event listener. This will only be called with handlers that have previously been passed to registerTransitionEndHandler calls.
registerDocumentKeydownHandler(handler: EventListener) => voidRegisters an event handler on the document object for a keydown event.
deregisterDocumentKeydownHandler(handler: EventListener) => voidDeregisters an event handler on the document object for a keydown event.
getDrawerWidth() => numberReturns the current drawer width, in pixels.
setTranslateX(value: number) => voidSets the current position for the drawer, in pixels from the border.
getFocusableElements() => NodeListReturns the node list of focusable elements inside the drawer.
saveElementTabState(el: Element) => voidSaves the current tab index for the element in a data property.
restoreElementTabState(el: Element) => voidRestores the saved tab index (if any) for an element.
makeElementUntabbable(el: Element) => voidMakes an element untabbable.
notifyOpen() => voidDispatches an event notifying listeners that the drawer has been opened.
notifyClose() => voidDispatches an event notifying listeners that the drawer has been closed.
isRtl() => booleanReturns boolean indicating whether the current environment is RTL.
isDrawer(el: Element) => booleanReturns boolean indicating whether the provided element is the drawer container sub-element.

Temporary drawer usage

A temporary drawer is usually closed, sliding out at a higher elevation than the content when opened. It is appropriate for any display size.

<aside class="mdc-drawer mdc-drawer--temporary mdc-typography">
  <nav class="mdc-drawer__drawer">
    <header class="mdc-drawer__header">
      <div class="mdc-drawer__header-content">
        Header here
      </div>
    </header>
    <nav id="icon-with-text-demo" class="mdc-drawer__content mdc-list">
      <a class="mdc-list-item mdc-list-item--activated" href="#">
        <i class="material-icons mdc-list-item__graphic" aria-hidden="true">inbox</i>Inbox
      </a>
      <a class="mdc-list-item" href="#">
        <i class="material-icons mdc-list-item__graphic" aria-hidden="true">star</i>Star
      </a>
    </nav>
  </nav>
</aside>
let drawer = new mdc.drawer.MDCTemporaryDrawer(document.querySelector('.mdc-drawer--temporary'));
document.querySelector('.menu').addEventListener('click', () => drawer.open = true);

Headers and toolbar spacers

Temporary drawers can use toolbar spacers, headers, or neither.

A toolbar spacer adds to the drawer the same amount of space that the toolbar takes up in your application. This is very useful for visual alignment and consistency. Note that you can place content inside the toolbar spacer.

<aside class="mdc-drawer mdc-drawer--temporary mdc-typography">
  <nav class="mdc-drawer__drawer">

    <div class="mdc-drawer__toolbar-spacer"></div>

    <nav id="icon-with-text-demo" class="mdc-drawer__content mdc-list">
      <a class="mdc-list-item mdc-list-item--activated" href="#">
        <i class="material-icons mdc-list-item__graphic" aria-hidden="true">inbox</i>Inbox
      </a>
      <a class="mdc-list-item" href="#">
        <i class="material-icons mdc-list-item__graphic" aria-hidden="true">star</i>Star
      </a>
    </nav>
  </nav>
</aside>

A header, on the other hand, is a large rectangular area that maintains a 16:9 ratio. It's often used for user account selection. It uses an outer mdc-drawer__header for positioning, with an inner mdc-drawer__header-content for placing the actual content, which will be bottom-aligned.

<aside class="mdc-drawer mdc-drawer--temporary mdc-typography">
  <nav class="mdc-drawer__drawer">

    <header class="mdc-drawer__header">
      <div class="mdc-drawer__header-content">
        Header content goes here
      </div>
    </header>

    <nav id="icon-with-text-demo" class="mdc-drawer__content mdc-list">
      <a class="mdc-list-item mdc-list-item--activated" href="#">
        <i class="material-icons mdc-list-item__graphic" aria-hidden="true">inbox</i>Inbox
      </a>
      <a class="mdc-list-item" href="#">
        <i class="material-icons mdc-list-item__graphic" aria-hidden="true">star</i>Star
      </a>
    </nav>
  </nav>
</aside>

CSS classes:

ClassDescription
mdc-drawerMandatory. Needs to be set on the root element of the component.
mdc-drawer--temporaryMandatory. Needs to be set on the root element of the component.
mdc-drawer__drawerMandatory. Needs to be set on the container node for the drawer content.
mdc-drawer__contentOptional. Should be set on the list of items inside the drawer.
mdc-drawer__toolbar-spacerOptional. Add to node to provide the matching amount of space for toolbar.
mdc-drawer__headerOptional. Add to container node to create a 16:9 drawer header.
mdc-drawer__header-contentOptional. Add to content node inside mdc-temporary-drawer__header.

Using the JS Component

MDC Temporary Drawer ships with a Component / Foundation combo which allows for frameworks to richly integrate the correct drawer behaviors into idiomatic components.

Including in code

ES2015
import {MDCTemporaryDrawer, MDCTemporaryDrawerFoundation, util} from '@material/drawer';
CommonJS
const mdcDrawer = require('mdc-drawer--temporary');
const MDCTemporaryDrawer = mdcDrawer.MDCTemporaryDrawer;
const MDCTemporaryDrawerFoundation = mdcDrawer.MDCTemporaryDrawerFoundation;
const util = mdcDrawer.util;
AMD
require(['path/to/mdc-drawer'], mdcDrawer => {
  const MDCTemporaryDrawer = mdcDrawer.MDCTemporaryDrawer;
  const MDCTemporaryDrawerFoundation = mdcDrawer.MDCTemporaryDrawerFoundation;
  const util = mdcDrawer.util;
});
Global
const MDCTemporaryDrawer = mdc.drawer.MDCTemporaryDrawer;
const MDCTemporaryDrawerFoundation = mdc.drawer.MDCTemporaryDrawerFoundation;
const util = mdc.drawer.util;

Automatic Instantiation

If you do not care about retaining the component instance for the temporary drawer, simply call attachTo() and pass it a DOM element.

mdc.drawer.MDCTemporaryDrawer.attachTo(document.querySelector('.mdc-drawer--temporary'));

Manual Instantiation

Temporary drawers can easily be initialized using their default constructors as well, similar to attachTo.

import {MDCTemporaryDrawer} from '@material/drawer';

const drawer = new MDCTemporaryDrawer(document.querySelector('.mdc-drawer--temporary'));

Handling events

When the drawer is opened or closed, the component will emit a MDCTemporaryDrawer:open or MDCTemporaryDrawer:close custom event with no data attached. Events get emitted only when the drawer toggles its opened state, i.e. multiple consecutive drawer.open = true calls will result in only one MDCTemporaryDrawer:open.

Using the Foundation Class

MDC Temporary Drawer ships with an MDCTemporaryDrawerFoundation class that external frameworks and libraries can use to integrate the component. As with all foundation classes, an adapter object must be provided. The adapter for temporary drawers must provide the following functions, with correct signatures:

Method SignatureDescription
addClass(className: string) => voidAdds a class to the root element.
removeClass(className: string) => voidRemoves a class from the root element.
hasClass(className: string) => booleanReturns boolean indicating whether element has a given class.
eventTargetHasClass(target: EventTarget, className: string) => booleanReturns true if target has className, false otherwise.
addBodyClass(className: string) => voidAdds a class to the body.
removeBodyClass(className: string) => voidRemoves a class from the body.
hasNecessaryDom() => booleanReturns boolean indicating whether the necessary DOM is present (namely, the mdc-drawer__drawer drawer container).
registerInteractionHandler(evt: string, handler: EventListener) => voidAdds an event listener to the root element, for the specified event name.
deregisterInteractionHandler(evt: string, handler: EventListener) => voidRemoves an event listener from the root element, for the specified event name.
registerDrawerInteractionHandler(evt: string, handler: EventListener) => voidAdds an event listener to the drawer container sub-element, for the specified event name.
deregisterDrawerInteractionHandler(evt: string, handler: EventListener) => voidRemoves an event listener from drawer container sub-element, for the specified event name.
registerTransitionEndHandler(handler: EventListener) => voidRegisters an event handler to be called when a transitionend event is triggered on the drawer container sub-element element.
deregisterTransitionEndHandler(handler: EventListener) => voidDeregisters an event handler from a transitionend event listener. This will only be called with handlers that have previously been passed to registerTransitionEndHandler calls.
registerDocumentKeydownHandler(handler: EventListener) => voidRegisters an event handler on the document object for a keydown event.
deregisterDocumentKeydownHandler(handler: EventListener) => voidDeregisters an event handler on the document object for a keydown event.
getDrawerWidth() => numberReturns the current drawer width, in pixels.
setTranslateX(value: number) => voidSets the current position for the drawer, in pixels from the border.
updateCssVariable(value: string) => voidSets a CSS custom property, for controlling the current background opacity when manually dragging the drawer.
getFocusableElements() => NodeListReturns the node list of focusable elements inside the drawer.
saveElementTabState(el: Element) => voidSaves the current tab index for the element in a data property.
restoreElementTabState(el: Element) => voidRestores the saved tab index (if any) for an element.
makeElementUntabbable(el: Element) => voidMakes an element untabbable.
notifyOpen() => voidDispatches an event notifying listeners that the drawer has been opened.
notifyClose() => voidDispatches an event notifying listeners that the drawer has been closed.
isRtl() => booleanReturns boolean indicating whether the current environment is RTL.
isDrawer(el: Element) => booleanReturns boolean indicating whether the provided element is the drawer container sub-element.

The util API

External frameworks and libraries can use the following utility methods when integrating a component.

util.remapEvent(eventName, globalObj = window) => String

Remap touch events to pointer events, if the browser doesn't support touch events.

util.getTransformPropertyName(globalObj = window, forceRefresh = false) => String

Choose the correct transform property to use on the current browser.

util.supportsCssCustomProperties(globalObj = window) => Boolean

Determine whether the current browser supports CSS properties.

util.applyPassive(globalObj = window, forceRefresh = false) => object

Determine whether the current browser supports passive event listeners, and if so, use them.

util.saveElementTabState(el) => void

Save the tab state for an element.

util.restoreElementTabState(el) => void

Restore the tab state for an element, if it was saved.

tutorbook-navigation@enbock/time-tracker@zentek/drawerpwa-test-hpwa-test1pwa-test2sot-incubator@beezydev/drawermrcwmaterial-components-web@everything-registry/sub-chunk-584preact-material-componentspreact-material-components-mgrmyg-drawer@dev.mohe/mwc-drawer@detachhead/smui-drawerbw-material@companick/react-drawer@tutorbook/navigation@worm425/betsy-web-components@types/material__draweraurelia-material-uiaurelia-mdc-ui@arterial/drawer@betsybot/betsy-web-components@aurelia-mdc-web/drawer@aurelia-material-components/drawer@aurelia2-mdc-web/drawer@betazuul/drawer@authentic/mwc-drawer@bitchin/react-material-web@blackpurl/web-components@defense-unicorns/unicorn-ui@angular/material@angular/material-experimental@whatoplay/react-drawer@pmwcs/drawervue-material-design-components@xdam/ember-partials@gmvdev/materialsclosure-react-drawer@hegdemahesh/moonraft-ui-element-sidebargesdisc-componentsjsonresume-theme-material-designmaterial-imbamaterial-toolboxreact-material-web-componentsreact-mdc@o-rango/orango-material-design@pitaya-components/drawer@openremote/or-mwc-components@morioh/materialstencil-starter-sumoski@emuanalytics/flow-rdftest-rsmdcsvelte-arcadiast-materialsvmd@smui/drawer@react-mdc/drawer@react.material/drawer@preact-material-components/drawer@qbcart/eshop-app-shell@rmwc/drawer@robertkern/vue-materialuui-components@plonquo/ember-material-components@inovex.de/elements@hieunv/react-mdcember-material-componentsember-cli-mdc-drawereasyfyv3-presentationdeps@infinitebrahmanuniverse/nolb-_mate@leanup/material-core@mcw/drawer@mcwv/drawer@material/react-drawer@materials-elements/core@materials-elements/site@materials-ui/core@materials-ui/site@mdc-react/drawer@mdc-stencil/drawer@material/mwc-drawer@mhamrah/svelte-material-ui@materialr/drawer
14.0.0

2 years ago

13.0.0

3 years ago

12.0.0

3 years ago

11.0.0

3 years ago

10.0.0

3 years ago

9.0.0

3 years ago

8.0.0

3 years ago

7.0.0

4 years ago

6.0.0

4 years ago

5.1.0

4 years ago

5.0.0

4 years ago

4.0.0

4 years ago

3.2.0

5 years ago

4.0.0-canary.1

5 years ago

4.0.0-canary.0

5 years ago

3.1.1

5 years ago

4.0.0-alpha.0

5 years ago

3.1.0

5 years ago

3.1.0-alpha.0

5 years ago

3.0.0

5 years ago

3.0.0-alpha.1

5 years ago

3.0.0-alpha.0

5 years ago

2.3.0

5 years ago

2.1.1

5 years ago

2.0.0

5 years ago

1.1.1

5 years ago

1.1.0

5 years ago

1.0.1

5 years ago

1.0.0

5 years ago

1.0.0-1

5 years ago

1.0.0-0

5 years ago

0.44.1

5 years ago

0.44.0

5 years ago

0.43.0

5 years ago

0.42.0

5 years ago

0.41.1

5 years ago

0.41.0

5 years ago

0.40.1

6 years ago

0.40.0

6 years ago

0.39.3

6 years ago

0.39.2

6 years ago

0.39.1

6 years ago

0.39.0

6 years ago

0.39.0-0

6 years ago

0.38.0

6 years ago

0.37.1

6 years ago

0.36.1

6 years ago

0.36.0

6 years ago

0.35.0

6 years ago

0.34.0

6 years ago

0.33.0

6 years ago

0.30.0

6 years ago

0.29.0

6 years ago

0.28.0

6 years ago

0.27.0

6 years ago

0.26.0

6 years ago

0.25.0

6 years ago

0.24.0

6 years ago

0.5.9

7 years ago

0.5.8

7 years ago

0.5.7

7 years ago

0.5.6

7 years ago

0.5.5

7 years ago

0.5.4

7 years ago

0.5.3

7 years ago

0.5.2

7 years ago

0.5.1

7 years ago

0.5.0

7 years ago

0.4.3

7 years ago

0.4.2

7 years ago

0.4.1

7 years ago

0.4.0

7 years ago

0.3.1

7 years ago

0.3.0

7 years ago

0.2.0

7 years ago

0.1.4

7 years ago

0.1.3

7 years ago

0.1.2

7 years ago

0.1.1

7 years ago

0.1.0

7 years ago