Skip to content

A simple side drawer written as HTML custom element

License

Notifications You must be signed in to change notification settings

wes-goulet/side-drawer

Repository files navigation

Build Published on webcomponents.org npm

side-drawer

A simple, animating side drawer built as a Web Component

side-drawer demo

Breaking Change in v4.x

This custom element now uses a standard dialog under the hood. As of October 2023 there are some browser bugs around dialog ::backdrop not seeing CSS variables. As a result the --side-drawer-backdrop-filter, --side-drawer-overlay-opacity and --side-drawer-overlay-transition variables will not work in some browsers. If you need to support these browsers you can use v3.x of this component until the browser bugs are fixed.

Installation

You can integrate side-drawer via <script> tag or via NPM.

Via <script> tag

In the <head> of your index.html put a script tag like this:

<script
  type="module"
  src="https://unpkg.com/side-drawer/side-drawer.js"
></script>

<!-- Or use the minified version -->
<script
  type="module"
  src="https://unpkg.com/side-drawer/side-drawer.min.js"
></script>

Now you can use the side-drawer element anywhere in your html, JSX, template, etc.

Via NPM

npm install side-drawer --save

And then you need to import the module before you can use it in your html/jsx/template:

import "side-drawer";

Web Component Browser Support

This web component uses HTML templates, the shadow DOM, and custom elements. If you need to polyfill for any of these standards then take a look at the web components polyfill.

API and Customization

Attributes/Properties

  • open
    • Add this attribute to open the drawer.
      • Example: <side-drawer open></side-drawer>
    • Set the property in Javascript to imperatively toggle the drawer
      • Example: drawer.open = true
    • In (p)react you might need to set undefined in your JSX (since false !== undefined for html attribute existence)
      • Example: <side-drawer open={this.state.isDrawerOpen || undefined}></side-drawer>
  • right
    • Add this attribute so the drawer opens from the right instead of the left.
      • Example: <side-drawer right></side-drawer>

Events

  • open
    • Raised when the drawer is opened.
    • Example: drawer.addEventListener("open", handleOpen())
    • When subscribing in html listen for onopen
      • Ex: <side-drawer onopen="handleOpen()">
  • close -Raised when the drawer is closed.
    • Example: drawer.addEventListener("close", handleClose())
    • When subscribing in html listen for onclose
      • Ex: <side-drawer onclose="handleClose()">

Styling

You can style the side-drawer element as you would any regular element, in CSS. A list of supported CSS properties are below, along with the default values.

side-drawer {
  background-color: #ffffff;
  width: 350px;
  max-width: 75vw;
  z-index: 10;
  border-top-right-radius: 0;
  border-bottom-right-radius: 0;
}

You can customize styling with the following CSS variables:

Variable Default Description
--side-drawer-transition transform 0.25s ease-out The open/close transition for the drawer (should be "transform")
--side-drawer-backdrop-filter none The backdrop-filter for both the drawer and the overlay that appears to the right of the drawer (when it's open)
--side-drawer-overlay-transition opacity linear 0.25s The transition for the overlay that appears to the right of the drawer (when it's open)
--side-drawer-overlay-opacity 0.7 The opacity of the overlay

Contribute

This project is built with standard HTML/CSS/JS, no frameworks or special web-component compilers here (for maximum simplicity and minimum size). If you want to learn more about writing custom elements see MDN or this web.dev page.

The source for this web component is contained in side-drawer.js and example usage is in index.html. To debug/run the example you can just open index.html in a browser. For a hot-reload developer experience try using live server in vscode.

You will need the dev dependencies of this project installed to run the post-commit hooks.

npm install