use-hid

Talk to human-interface devices with the WebHID API.


Package	`@vizejs/composable/use-hid`
Own the source	`vize lib pull composable:use-hid`
Runtime exports	`useHID`
Gzip budget	2304 B

Usage

import { useHID } from "@vizejs/composable/use-hid";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useHID`	system	experimental	deterministic-fallback	caller-managed	reactive-scope, returned-value	web, desktop	`window`	`tryOnScopeDispose`

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.

Member	Type	Description
`vendorId`?	`number`	USB vendor id.
`productId`?	`number`	USB product id.
`usagePage`?	`number`	HID usage page.
`usage`?	`number`	HID usage.

`HIDDeviceLike`

Minimal HIDDevice used by useHID.

Member	Type	Description
`opened`	`boolean`	Whether the device is open.
`vendorId`	`number`	USB vendor id.
`productId`	`number`	USB product id.
`productName`	`string`	Product name.
`open`	`() => Promise<void>`	Open the device.
`close`	`() => Promise<void>`	Close the device.
`sendReport`	`(reportId: number, data: BufferSource) => Promise<void>`	Send an output report.
`sendFeatureReport`	`(reportId: number, data: BufferSource) => Promise<void>`	Send a feature report.
`receiveFeatureReport`	`(reportId: number) => Promise<DataView>`	Read a feature report.

`HIDHost`

navigator.hid-like capability used by useHID.

Member	Type	Description
`getDevices`	`() => Promise<HIDDeviceLike[]>`	Devices the page already has access to.
`requestDevice`	`(options: { readonly filters: HIDDeviceFilter[] }) => Promise<HIDDeviceLike[]>`	Prompt the user for devices.

`HIDDeviceInfo`

Plain, reactive-friendly description of a granted device.

Member	Type	Description
`device`	`HIDDeviceLike`	The live device, for passing back to the actions.
`vendorId`	`number`	USB vendor id.
`productId`	`number`	USB product id.
`productName`	`string`	Product name.
`opened`	`boolean`	Whether the device was open when the list was refreshed.

`HIDInputReport`

An input report received from an open device.

Member	Type	Description
`device`	`HIDDeviceLike`	Device that sent the report.
`reportId`	`number`	Report id (`0` when the device does not use report ids).
`data`	`DataView`	Report payload.

`UseHIDOptions`

Options for useHID.

Member	Type	Description
`host`?	`MaybeRefOrGetter<HIDHost \| null \| undefined>`	`navigator.hid`-like capability.
`onInputReport`?	`(report: HIDInputReport) => void`	Receives input reports from every device opened through `HIDControls.open`.

`HIDControls`

Reactive state and actions returned by useHID.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether WebHID is available.
`devices`	`Readonly<ShallowRef<readonly HIDDeviceInfo[]>>`	Granted devices, refreshed on `connect` / `disconnect`, open and close.
`error`	`Readonly<ShallowRef<unknown>>`	Most recent failure.
`requestDevice`	`(filters?: HIDDeviceFilter[]) => Promise<readonly HIDDeviceLike[]>`	Prompt the user for devices (requires user activation).
`getDevices`	`() => Promise<readonly HIDDeviceInfo[]>`	Refresh `devices`.
`open`	`(device: HIDDeviceLike) => Promise<boolean>`	Open a device and start forwarding its input reports.
`close`	`(device: HIDDeviceLike) => Promise<boolean>`	Stop forwarding reports and close a device.
`sendReport`	`( device: HIDDeviceLike, reportId: number, data: BufferSource, ) => Promise<boolean>`	Send an output report.
`sendFeatureReport`	`( device: HIDDeviceLike, reportId: number, data: BufferSource, ) => Promise<boolean>`	Send a feature report.
`receiveFeatureReport`	`( device: HIDDeviceLike, reportId: number, ) => Promise<DataView \| undefined>`	Read a feature report.