# Quickstart

Get `navigator.bluetooth` working inside iOS Safari in under ten minutes. This page covers the two steps every WebBLE integration shares — install the Safari Web Extension, then load the polyfill in your page — and links out to framework-specific walkthroughs.

## 1. Install the WebBLE Safari Web Extension

WebBLE ships as a regular iOS app that registers a Safari Web Extension. Distributed through the App Store; no sideloading, no developer mode.

1. Open the App Store on iPhone and install **WebBLE**.
2. Launch the app once to finish first-run setup.
3. Open **Settings → Apps → Safari → Extensions → WebBLE** and enable the extension.
4. Tap **WebBLE** again, choose **Always Allow**, then **Always Allow on Every Website**.

The extension is now live on every tab. Safari exposes `navigator.bluetooth` on any HTTPS page that loads the WebBLE polyfill script.

## 2. Load the polyfill in your page

Pick one of two install modes:

**CDN (fastest to try):**

```html
<script src="https://cdn.ioswebble.com/v1.js"></script>
```

**npm (recommended for real projects):**

```bash
npm install @ios-web-bluetooth/core
```

```js
import '@ios-web-bluetooth/core/auto';
```

The core package is a zero-config polyfill. It detects the extension, mounts the W3C surface at `navigator.bluetooth`, and mounts the iOS-only vendor-prefixed surface at `window.webbleIOS`.

## 3. Verify it works

```js
if (await navigator.bluetooth.getAvailability()) {
  const device = await navigator.bluetooth.requestDevice({
    filters: [{ services: ['heart_rate'] }]
  });
  console.log('Paired with', device.name);
}
```

If `getAvailability()` returns `false`, the user has not enabled the extension on this site; see [Extension not detected](troubleshooting/extension-not-detected.md).

## Framework-specific walkthroughs

- [HTML / plain JS](quickstart-html.md)
- [React](quickstart-react.md)
- [Vue](quickstart-vue.md)
- [Svelte / SvelteKit](quickstart-svelte.md)
- [Angular](quickstart-angular.md)
- [Next.js](quickstart-next.md)

## Next steps

- [API reference](api-reference.md) — every documented method
- [Recipes](recipes.md) — heart-rate, battery, CGM, lock, beacon, peripheral
- [Premium APIs](premium.md) — `window.webbleIOS` surface
- [Troubleshooting](troubleshooting/extension-not-detected.md)