use-usb

Talk to USB devices with the WebUSB API.

Minimal setup

Use a Vue 3.5+ project with Vue SFC compilation configured (see Vite+ integration).

vp install @vizejs/composable

Import the entry directly. Call lifecycle-bound utilities inside <script setup> so cleanup follows the component scope; consult the runtime contract for this entry's SSR and hydration behavior.

import { useUSB } from "@vizejs/composable/use-usb";

Try it

Grant access to a USB device

Let the reader choose a USB device such as a label printer and list the devices already allowed.

Open the interactive example

What to observe: Choose a USB device opens the chooser where WebUSB exists; previously allowed devices appear without asking again.

selectConfiguration, claimInterface and transfers are available after open. Every example renders a neutral message until it mounts, so server and client markup match, and then explains what to do when the browser lacks the API.

Compare the initial and interacted states

Copy the example

Save this complete SFC in your Vue project. Its public imports and source are the same ones executed in the preview.

<script setup lang="ts">
import { useMounted } from "@vizejs/composable/use-mounted";
import { useUSB } from "@vizejs/composable/use-usb";

const mounted = useMounted();
const { supported, devices, requestDevice } = useUSB();
</script>

<template>
  <div class="composable-example">
    <p>Let the reader grant access to a USB device, such as a label printer.</p>
    <button type="button" :disabled="!mounted || !supported" @click="() => requestDevice([])">
      Choose a USB device
    </button>
    <ul aria-label="Allowed devices">
      <li v-for="item in devices" :key="`${item.vendorId}-${item.productId}`">
        {{ item.productName }}
      </li>
    </ul>
    <output aria-live="polite">{{
      !mounted
        ? "Checking browser support…"
        : supported
          ? `${devices.length} devices allowed.`
          : "WebUSB is not available in this browser."
    }}</output>
  </div>
</template>

Runtime contract

API

useUSB

Talk to USB devices with the WebUSB API. devices lists granted devices as plain snapshots and follows the host's connect / disconnect events. The device actions are thin wrappers over USBDevice that resolve to a boolean or the transfer result and record failures in error instead of rejecting. Host listeners are removed and sessions opened through open() are closed when the owning reactive scope stops; outside a scope call close() per device. Server rendering: supported is false and devices is empty.

function useUSB(options: UseUSBOptions = {}): USBControls

const usb = useUSB();
const device = await usb.requestDevice([{ vendorId: 0x2341 }]);
if (device && (await usb.open(device))) await usb.claimInterface(device, 0);

Types

USBDeviceFilter

Device filter for requestDevice.

USBInTransferResultLike

Result of an IN transfer.

USBOutTransferResultLike

Result of an OUT transfer.

USBControlTransferSetup

Setup packet of a control transfer.

USBDeviceLike

Minimal USBDevice used by useUSB.

USBHost

navigator.usb-like capability used by useUSB.

USBDeviceInfo

Plain, reactive-friendly description of a granted device.

UseUSBOptions

Options for useUSB.

USBControls

Reactive state and actions returned by useUSB.