Integrate

The React components

@alivelabs/troupe-react is the set of themable React components that Troupe Studio is built from, for showing and driving devices in your own page. This page covers DeviceScreen, the other components and theming.

Install

bun add --exact @alivelabs/troupe-react @alivelabs/troupe-client

Like the rest of Troupe, the packages are not on npm yet; Install has the status.

• react and react-dom 19.2 or newer are peer dependencies.
• The components run in a browser with WebSocket and WebCodecs. Server rendering is not supported.
• The package ships TypeScript sources, so your bundler must compile TypeScript inside node_modules: Vite, Bun.build and esbuild do.
• Import the stylesheet once. Your app needs no Tailwind or other CSS framework.

A live device

DeviceScreen shows a session's live stream and lets the viewer drive it.

import { createClient } from '@alivelabs/troupe-client'
import { DeviceScreen } from '@alivelabs/troupe-react'
import '@alivelabs/troupe-react/styles.css'

const troupe = createClient({ baseUrl, token })
const stream = await troupe.call('streams.ticket', { sessionId, cap: 'drive' })

<DeviceScreen
  stream={stream}
  getTicket={(cap) => troupe.call('streams.ticket', { sessionId, cap: cap ?? 'drive' })}
/>

stream is the first { url, ticket }. getTicket mints another when the stream needs one: after a ticket is refused, and when the viewer presses Take control.

The component handles the rest:

• It decodes the video onto a canvas and reconnects when the socket drops.
• It sends pointer, wheel and keyboard input while the viewer drives. Shift+Escape leaves the device, since Tab and Escape go to it.
• Its toolbar shows the controls the device offers now: Back, Home and the app switcher, Rotate, Lock or Power, Volume, and a Screenshot button that saves the picture as a PNG.
• Its status line says who drives and why input is unavailable when it is.
• It releases the decoder while the page is hidden.

The other components

Each of these takes a client prop, or reads the client from a TroupeProvider above it.

Together they make an inspector:

import { useState } from 'react'
import type { TroupeClient } from '@alivelabs/troupe-client'
import type { StreamSource } from '@alivelabs/troupe-client/stream'
import type { SessionId, StreamCap } from '@alivelabs/troupe-protocol'
import {
  A11yTree,
  type DeviceHighlight,
  DeviceScreen,
  Logs,
  TroupeProvider,
} from '@alivelabs/troupe-react'

interface InspectorProps {
  troupe: TroupeClient
  sessionId: SessionId
  stream: StreamSource
  getTicket: (cap?: StreamCap) => Promise<StreamSource>
}

function Inspector({ troupe, sessionId, stream, getTicket }: InspectorProps) {
  const [highlight, setHighlight] = useState<DeviceHighlight | null>(null)
  const [driven, setDriven] = useState(0)

  return (
    <TroupeProvider client={troupe}>
      <DeviceScreen
        stream={stream}
        getTicket={getTicket}
        highlight={highlight}
        onInput={() => setDriven((count) => count + 1)}
      />
      <A11yTree sessionId={sessionId} onHighlight={setHighlight} refreshKey={driven} />
      <Logs sessionId={sessionId} />
    </TroupeProvider>
  )
}

Hovering a line in the tree outlines that element on the device. Driving the device changes refreshKey, so the tree takes a new snapshot.

For a view of your own, the package also exports the logic behind the components: useTroupeClient, useResource for loading a value with its state, ariaRows and suggestLocator for the tree, appendLogs and filterLogs for logs, applySessionEvent and buildSpec for sessions, and describeError.

Text that comes from a device or an app, such as an accessibility label or a log line, is always rendered as text, never as HTML.

Theming

styles.css is one plain stylesheet. Its classes start with troupe-, and it has no global reset, so it does not change the rest of your page.

Every colour, border and focus ring reads one of 24 custom properties. Each has a light and a dark default through CSS light-dark(), so the components follow your page's color-scheme with no work. To theme them, set the properties on a container:

.device-panel {
  color-scheme: dark;
  --troupe-bg: #0b1020;
  --troupe-surface: #141a2e;
  --troupe-border-focus: #9d7bff;
  --troupe-accent: #2a2350;
}

The package exports the list as THEME_VARIABLES. The bezel is not themed: a phone's frame is dark on any page.

Next

• The live stream: what DeviceScreen does underneath
• The client SDK: the client the components call
• Troupe Studio: the app built from these components