use-hid

Talk to human-interface devices with the WebHID 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 { useHID } from "@vizejs/composable/use-hid";

Try it

Connect a HID device

Ask for access to a keyboard-like device such as a macro keypad and list the devices already allowed.

Open the interactive example

What to observe: Choose a device opens the browser's HID chooser where WebHID exists; allowed devices are listed below.

Pass vendor and product filters to requestDevice. onInputReport receives reports 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 { useHID } from "@vizejs/composable/use-hid";
import { useMounted } from "@vizejs/composable/use-mounted";

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

<template>
  <div class="composable-example">
    <p>Connect a USB or Bluetooth HID device, such as a macro keypad.</p>
    <button type="button" :disabled="!mounted || !supported" @click="() => requestDevice([])">
      Choose a device
    </button>
    <ul aria-label="Connected 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.`
          : "WebHID is not available in this browser."
    }}</output>
  </div>
</template>

Runtime contract

API

useHID

Talk to human-interface devices with the WebHID API. devices lists granted devices as plain snapshots and follows the host's connect / disconnect events. Devices opened through open() forward inputreport events to onInputReport. Every action resolves to a boolean or value and records failures in error. Report listeners are removed and opened devices closed when the owning reactive scope stops; outside a scope call close() per device. Server rendering: supported is false and devices is empty. Inside a component the host is resolved after mounting, so hydration renders this server state first.

function useHID(options: UseHIDOptions = {}): HIDControls

const hid = useHID({ onInputReport: ({ reportId, data }) => read(reportId, data) });
const [device] = await hid.requestDevice([{ vendorId: 0x054c }]);
if (device) await hid.open(device);

Types

HIDDeviceFilter

Device filter for requestDevice.

HIDDeviceLike

Minimal HIDDevice used by useHID.

HIDHost

navigator.hid-like capability used by useHID.

HIDDeviceInfo

Plain, reactive-friendly description of a granted device.

HIDInputReport

An input report received from an open device.

UseHIDOptions

Options for useHID.

HIDControls

Reactive state and actions returned by useHID.