use-serial

Talk to serial devices with the Web Serial 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 { useSerial } from "@vizejs/composable/use-serial";

Try it

Read a microcontroller's log

Open a serial port and stream decoded text lines from a connected board.

Open the interactive example

What to observe: Connect a board opens the port chooser where Web Serial exists; incoming lines appear in the output area.

decode: "text" decodes chunks as UTF-8 and onData receives each chunk. Set the baud rate your board uses. 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 { ref } from "vue";
import { useMounted } from "@vizejs/composable/use-mounted";
import { useSerial } from "@vizejs/composable/use-serial";

const mounted = useMounted();
const lines = ref<string[]>([]);
const { supported, connected, requestPort, open, close } = useSerial({
  decode: "text",
  onData: (chunk) => {
    lines.value = [...lines.value, String(chunk)].slice(-5);
  },
});

async function connectBoard() {
  const port = await requestPort();
  if (port) await open(port, { baudRate: 115200 });
}
</script>

<template>
  <div class="composable-example">
    <p>Read log lines from a microcontroller over a serial port.</p>
    <div class="example-actions">
      <button type="button" :disabled="!mounted || !supported || connected" @click="connectBoard">
        Connect a board
      </button>
      <button type="button" :disabled="!connected" @click="() => close()">Disconnect</button>
    </div>
    <pre aria-label="Serial output">{{ lines.join("\n") }}</pre>
    <output aria-live="polite">{{
      !mounted
        ? "Checking browser support…"
        : supported
          ? connected
            ? "Reading from the board."
            : "Ready to connect."
          : "Web Serial is not available in this browser."
    }}</output>
  </div>
</template>

Runtime contract

API

useSerial

Talk to serial devices with the Web Serial API. requestPort() prompts for a port, open() opens it and starts a read loop that feeds onData with bytes or decoded text, write() sends text or bytes. ports follows the host's connect / disconnect events and a port's own disconnect closes the session. Failures land in error. The read loop is cancelled and the port closed when the owning reactive scope stops; outside a scope call close(). Server rendering: supported and connected are false, nothing is read.

function useSerial<const Decoding extends SerialDecoding = "bytes">( options: UseSerialOptions<Decoding> = {}, ): SerialControls

const serial = useSerial({ decode: "text", onData: (text) => log(text) });
const port = await serial.requestPort([{ usbVendorId: 0x2341 }]);
if (port) await serial.open(port, { baudRate: 115200 });

Types

SerialPortFilter

USB identifiers used to filter requestPort.

SerialOpenOptions

Line settings passed to SerialPort.open.

SerialPortLike

Minimal SerialPort used by useSerial.

SerialHost

navigator.serial-like capability used by useSerial.

UseSerialOptions

Options for useSerial.

SerialControls

Reactive state and actions returned by useSerial.