react-web-serial

React hooks and context provider for the Web Serial API.

Install

npm install react-web-serial

Usage

Examples

• Serial Monitor — Minimal serial monitor app with an Arduino echo sketch

Basic

import { SerialProvider, useSerialPort } from "react-web-serial";

const SerialMonitor = () => {
  const {
    isAvailableSerialApi,
    isConnected,
    isSubscribing,
    receivedData,
    error,
    connect,
    disconnect,
    write,
    startSubscribe,
    stopSubscribe,
    clearReceivedData,
  } = useSerialPort({
    options: { baudRate: 9600 },
  });

  if (!isAvailableSerialApi) {
    return <p>Web Serial API is not supported in this browser.</p>;
  }

  return (
    <div>
      <button onClick={connect} disabled={isConnected}>
        Connect
      </button>
      <button onClick={disconnect} disabled={!isConnected}>
        Disconnect
      </button>
      <button onClick={startSubscribe} disabled={!isConnected || isSubscribing}>
        Start Subscribe
      </button>
      <button onClick={stopSubscribe} disabled={!isSubscribing}>
        Stop Subscribe
      </button>
      <button onClick={() => write("hello")} disabled={!isConnected}>
        Send "hello"
      </button>
      <button onClick={clearReceivedData}>Clear</button>

      {error && <p>Error: {error.message}</p>}

      <ul>
        {receivedData.map((entry, i) => (
          <li key={i}>
            {entry.mode === "text" ? entry.value : Array.from(entry.value).join(", ")}
          </li>
        ))}
      </ul>
    </div>
  );
};

const App = () => (
  <SerialProvider>
    <SerialMonitor />
  </SerialProvider>
);

API

<SerialProvider>

Context provider. Wrap your app or component tree with this.

<SerialProvider>{children}</SerialProvider>

useSerialPort(params)

Parameters

| Name | Type | Required | Description | |------|------|----------|-------------| | options | SerialOptions | Yes | Options passed to port.open() (e.g. { baudRate: 9600 }) | | requestOptions | SerialPortRequestOptions | No | Filters for navigator.serial.requestPort() | | maxReceivedDataCount | number | No | Max entries in receivedData buffer. Default: 1000 | | mode | "text" \| "binary" | No | Data mode for startSubscribe. Default: "text" |

Return value

| Name | Type | Description | |------|------|-------------| | isAvailableSerialApi | boolean | Whether the browser supports Web Serial API | | port | SerialPortInfo \| null | Connected port (exposes getInfo and forget) | | isConnecting | boolean | Connection in progress | | isConnected | boolean | Port is connected | | isUserCancelled | boolean | User dismissed the port selection dialog | | isSubscribing | boolean | Actively reading data from the port | | receivedData | SerialReceivedDataEntry[] | Received data buffer | | error | Error \| null | Last error | | connect | () => Promise<void> | Open port selection dialog and connect | | disconnect | () => Promise<void> | Close the port | | write | (data: string \| Uint8Array) => Promise<boolean> | Write data to the port | | startSubscribe | () => void | Start reading data from the port | | stopSubscribe | () => Promise<void> | Stop reading data | | clearReceivedData | () => void | Clear the received data buffer |

Types

type SerialDataMode = "text" | "binary";

type SerialReceivedDataEntry =
  | { mode: "text"; timestamp: Date; value: string }
  | { mode: "binary"; timestamp: Date; value: Uint8Array };

Browser support

Web Serial API is available in Chromium-based browsers (Chrome, Edge, Opera). See Can I use for details.

License

MIT