# Toolbar API

> Every option on the toolbar's script tag, and the window.Fiddle API for controlling it from code.

## Script tag

```html
<script src="https://fiddle.fyi/embed.js" data-app="<app id>" data-branch="<branch>" async></script>
```

| Attribute | What it does |
| --- | --- |
| `data-app` | Your app's id. Required |
| `data-branch` | The branch the page was built from. Without it, Fiddle asks GitHub using the commit |
| `data-commit` | The commit it was built from |
| `data-environment` | The environment the page acts as, such as `QA` |
| `data-launcher` | `hidden`: no toolbar until someone opens it. Use in production |
| `data-shortcut` | Show and hide the bar. Default `alt+shift+f`; `mod+.` and the like; `none` |
| `data-comment-shortcut` | Comment mode on and off. Default `alt+shift+c`; `none` |
| `data-toolbar` | `page`: your own toolbar draws Fiddle's controls from `Fiddle.tool` |

The Vite plugin, `<FiddleToolbar>` and `load()` take the same options in camelCase.

## window.Fiddle

| Member | What it does |
| --- | --- |
| `open()`, `close()`, `toggle()` | Open or close the toolbar |
| `show()`, `hide()` | Show or hide the bar |
| `isOpen()` | Whether it's open |
| `set({ environment, navigate, stories, story, controls })` | Change settings at runtime |
| `on("open" \| "close" \| "ready", fn)` | Listen; returns an unsubscribe function |
| `tool` | Fiddle's controls, for a page that draws its own toolbar |

A `fiddle:ready` event on `window` says it's loaded.

## Single-page apps

Give Fiddle your router so a comment on another page opens without a reload:

```js
Fiddle.set({ navigate: (href) => router.navigate(href) })
```

## A Feedback button

```tsx
<button onClick={() => Fiddle.open()}>Feedback</button>
```

## When the toolbar can't load

If a page can't say its branch or isn't an allowed deployment, the toolbar shows Fiddle's mark with a dot whose menu explains the fix. The reason is also logged to the console, set on `window.__FIDDLE_UNAVAILABLE__` and sent as a `fiddle:unavailable` event.

## From npm

```ts
import { load } from "@basswood/fiddle/toolbar"

const fiddle = await load({ app: "<app id>", branch: "main" })
fiddle.open()
```
