https://github.com/wes-goulet/side-drawer
A simple side drawer written as HTML custom element
https://github.com/wes-goulet/side-drawer
Last synced: 14 days ago
JSON representation
A simple side drawer written as HTML custom element
- Host: GitHub
- URL: https://github.com/wes-goulet/side-drawer
- Owner: wes-goulet
- License: mit
- Created: 2019-01-16T02:05:08.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2024-04-29T15:57:00.000Z (12 months ago)
- Last Synced: 2025-03-24T05:24:33.360Z (about 1 month ago)
- Language: HTML
- Homepage: https://side-drawer.goulet.dev
- Size: 830 KB
- Stars: 41
- Watchers: 1
- Forks: 8
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
 [](https://www.webcomponents.org/element/side-drawer) [](https://npmjs.org/package/side-drawer)
# side-drawer
A simple, animating side drawer built as a Web Component
## [Demo](https://side-drawer.netlify.com/)
## 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.
- [Web Page Test for ::backdrop respecting CSS vars](https://wpt.fyi/results/html/semantics/interactive-elements/the-dialog-element/backdrop-inherits.html)
- [Chromium bug](https://bugs.chromium.org/p/chromium/issues/detail?id=827397)
- [Firefox bug](https://bugzilla.mozilla.org/show_bug.cgi?id=1855668)
- [Safari bug](https://bugs.webkit.org/show_bug.cgi?id=263834)
## Installation
You can integrate side-drawer via `` tag or via NPM.
### Via `<script>` tag
In the `<head>` of your index.html put a script tag like this:
```html
<script
type="module"
src="https://unpkg.com/side-drawer/side-drawer.js"
>
```
Now you can use the `side-drawer` element anywhere in your html, JSX, template, etc.
### Via NPM
```bash
npm install side-drawer --save
```
And then you need to import the module before you can use it in your html/jsx/template:
```js
import "side-drawer";
```
## Web Component Browser Support
This web component uses [HTML templates](https://caniuse.com/#feat=template), the [shadow DOM](https://caniuse.com/#feat=shadowdomv1), and [custom elements](https://caniuse.com/#feat=custom-elementsv1). If you need to polyfill for any of these standards then [take a look at the web components polyfill](https://github.com/webcomponents/webcomponentsjs).
## API and Customization
### Attributes/Properties
- `open`
- Add this attribute to open the drawer.
- Example: ``
- 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: ``
- `right`
- Add this attribute so the drawer opens from the right instead of the left.
- Example: ``
### Events
- `open`
- Raised when the drawer is opened.
- Example: `drawer.addEventListener("open", handleOpen())`
- When subscribing in html listen for `onopen`
- Ex: ``
- `close`
-Raised when the drawer is closed.
- Example: `drawer.addEventListener("close", handleClose())`
- When subscribing in html listen for `onclose`
- Ex: ``
### 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.
```css
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](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) or [this web.dev page](https://web.dev/web-components/).
The source for this web component is contained in [side-drawer.js](side-drawer.js) and example usage is in [index.html](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](https://marketplace.visualstudio.com/items?itemName=ritwickdey.LiveServer).
You will need the dev dependencies of this project installed to run the post-commit hooks.
```bash
npm install
```