> For the complete documentation index, see [llms.txt](https://docs.nickarce.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nickarce.com/etch-drawer/customization/javascript-api.md).

# Javascript API

Drawers are initialized automatically on page load. You only need to call `new Drawer(...)` if you are adding a drawer to the page dynamically after load.

For most use cases, the builder's prop panel is all you need. The JavaScript API is for situations where you need to control the Drawer from custom code — for example, opening it after a form submission, closing it from another component, or reacting when it opens or closes.

## Getting an instance

Each initialized drawer stores its instance on the wrapper element:

```javascript
const wrapper = document.querySelector('#my-drawer');
const drawer = wrapper._drawer;

if (drawer) drawer.open();
```

## Instance methods

| Method                   | What it does                                                                                           |
| ------------------------ | ------------------------------------------------------------------------------------------------------ |
| `drawer.open()`          | Opens the drawer                                                                                       |
| `drawer.close()`         | Closes the drawer with its normal animation                                                            |
| `drawer.close(duration)` | Closes the drawer in a specific number of seconds (e.g. `drawer.close(0.2)`)                           |
| `drawer.destroy()`       | Removes all event listeners and cleans up. Call this before removing the drawer element from the page. |

## Instance properties

| Property            | Type    | Description                                        |
| ------------------- | ------- | -------------------------------------------------- |
| `drawer.isOpen`     | boolean | `true` if the drawer is currently open             |
| `drawer.isDragging` | boolean | `true` if the user is actively dragging the drawer |

## Constructor options

Pass these when creating a drawer instance manually with `new Drawer(...)`.

Several options mirror builder props (`direction`, `passive`, `noDrag`, `handleOnly`). When both are set, the constructor option wins — the builder prop acts as the default.

| Option              | Description                                                                                                    | Type                                     | Default    | Builder prop          |
| ------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------- | --------------------- |
| `dismissible`       | Allow the user to close the drawer by clicking the overlay or pressing ESC                                     | boolean                                  | `true`     | —                     |
| `direction`         | Edge the drawer slides in from                                                                                 | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Open Direction        |
| `passive`           | Non-modal mode — no overlay, no focus trap, no body scroll lock                                                | boolean                                  | `false`    | Passive Mode          |
| `noDrag`            | Disable swipe-to-close entirely                                                                                | boolean                                  | `false`    | Disable Drag to Close |
| `handleOnly`        | Restrict drag-to-close to the handle bar only                                                                  | boolean                                  | `false`    | Handle Only           |
| `nested`            | Mark this as a nested drawer. Detected automatically in most cases — you rarely need to set this manually.     | boolean                                  | auto       | —                     |
| `scrollLockTimeout` | Milliseconds to wait after a scroll before allowing drag-to-close. Prevents accidental closes after scrolling. | number                                   | `100`      | —                     |
| `closeThreshold`    | Fraction of the drawer's size the user must drag before it closes on release. `0.25` = 25%.                    | number                                   | `0.25`     | —                     |

## Events

Drawers dispatch `CustomEvent`s on the wrapper element. They bubble, so you can listen on the wrapper or any ancestor.

| Event            | When it fires                          | `event.detail`                                                               |
| ---------------- | -------------------------------------- | ---------------------------------------------------------------------------- |
| `drawer:open`    | After the drawer opens                 | none                                                                         |
| `drawer:close`   | After the drawer closes                | none                                                                         |
| `drawer:drag`    | Every frame while the user is dragging | `{ event, percentage }` — `percentage` is `0` to `1`                         |
| `drawer:release` | When the user releases after a drag    | `{ event, snappedBack }` — `snappedBack` is `true` if the drawer stayed open |

`event.detail.event` is the underlying pointer event.

### Callbacks (deprecated)

The previous callback options (`onOpen`, `onClose`, `onDrag`, `onRelease`) still work for backwards compatibility, but log a deprecation warning. New code should use the events above.

| Callback    | Equivalent event | Arguments              |
| ----------- | ---------------- | ---------------------- |
| `onOpen`    | `drawer:open`    | none                   |
| `onClose`   | `drawer:close`   | none                   |
| `onDrag`    | `drawer:drag`    | `(event, percentage)`  |
| `onRelease` | `drawer:release` | `(event, snappedBack)` |

## Static methods

| Method          | Description                                                                                                                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Drawer.init()` | Scans the page for all `.c-drawer__wrapper` elements and initializes any that haven't been set up yet. Runs automatically on page load — call it manually only if you've added new drawer elements to the DOM after load. |

## Examples

**Open a drawer from a button click:**

```javascript
const drawer = document.querySelector('#my-drawer')._drawer;

document.querySelector('#open-btn').addEventListener('click', () => {
  drawer.open();
});
```

**Open a drawer after a form submits:**

```javascript
const form = document.querySelector('#signup-form');
const drawer = document.querySelector('#confirmation-drawer')._drawer;

form.addEventListener('submit', (e) => {
  e.preventDefault();
  // ... handle the submission ...
  drawer.open();
});
```

**Run code when the drawer opens or closes:**

```javascript
const wrapper = document.querySelector('#my-drawer');

wrapper.addEventListener('drawer:open', () => {
  console.log('Drawer opened');
});

wrapper.addEventListener('drawer:close', () => {
  console.log('Drawer closed');
});
```

**Show a progress indicator while dragging:**

```javascript
const wrapper = document.querySelector('#my-drawer');
const progressBar = document.querySelector('#drag-progress');

wrapper.addEventListener('drawer:drag', (e) => {
  progressBar.style.width = `${e.detail.percentage * 100}%`;
});

wrapper.addEventListener('drawer:release', () => {
  progressBar.style.width = '0%';
});
```

**Close a drawer quickly after a success action:**

```javascript
const drawer = document.querySelector('#my-drawer')._drawer;

// Close in 0.2 seconds instead of the default 0.5
drawer.close(0.2);
```

**Toggle open/closed:**

```javascript
const drawer = document.querySelector('#my-drawer')._drawer;

if (drawer.isOpen) {
  drawer.close();
} else {
  drawer.open();
}
```

**Clean up before removing a drawer from the page:**

```javascript
const drawer = document.querySelector('#my-drawer')._drawer;

drawer.destroy();
document.querySelector('#my-drawer').remove();
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nickarce.com/etch-drawer/customization/javascript-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.