React Device Lab

react-device-lab is an open-source React toolkit for reviewing responsive web applications in exact, named CSS viewports. It combines an iframe-backed preview engine, 85 device profiles, independent authored frames, a searchable catalog, orientation and display scaling, route tools, safe-area visualization, and configurable browser-environment scenarios.

It is a responsive application preview tool, not an iOS, Android, browser-engine, or hardware emulator. Use it to catch layout and interaction problems early; verify OS-owned behavior on real devices and platform tooling.

Features

• Exact iframe viewport dimensions with portrait and landscape orientation.
• Fit, 50%, 75%, 100%, and custom visual scale without changing media-query dimensions.
• 85 phones, foldables, tablets, laptops, desktops, and ultrawide profiles.
• Independently authored CSS/React skins with notches, camera cutouts, buttons, fold creases, laptop bases, and monitor stands.
• Same-origin SPA route inspection and an exact-origin postMessage bridge for cooperating cross-origin applications.
• Searchable/grouped device selection, custom viewports, destinations, reload, and open-in-new-tab actions.
• Full-screen desktop workspace with independent stage/panel scrolling and a responsive narrow layout.
• Light/dark themes and product-neutral --rdl-* CSS custom properties.
• Optional safe-area, virtual-keyboard, locale, direction, text-scale, accessibility, pointer, fold, and permission scenarios.
• SSR-safe ESM imports, TypeScript declarations, and React 18/19 peer support.

Installation

npm install react-device-lab

Import the stylesheet once in the application that hosts the lab.

import { DevicePreviewLab } from "react-device-lab";
import "react-device-lab/styles.css";

export function PreviewRoute() {
  return (
    <DevicePreviewLab
      src="http://localhost:3000"
    />
  );
}

The target URL must permit framing. For production targets, configure a narrow Content Security Policy frame-ancestors allow-list and review the security policy and iframe guidance.

Destinations and controlled state

import {
  DevicePreviewLab,
  type PreviewRouteState,
} from "react-device-lab";
import "react-device-lab/styles.css";

const destinations = [
  { id: "home", label: "Home", src: "http://localhost:3000/" },
  { id: "settings", label: "Settings", src: "http://localhost:3000/settings" },
];

export function ReviewWorkspace() {
  const handleRoute = (route: PreviewRouteState) => {
    console.info("Embedded route:", route.pathname);
  };

  return (
    <DevicePreviewLab
      defaultDeviceId="iphone-17-pro"
      destinations={destinations}
      onRouteChange={handleRoute}
      src={destinations[0].src}
      title="Responsive review"
    />
  );
}

The embedded application remains authoritative for live SPA navigation. onRouteChange observes normalized same-origin or bridge route state without remounting the iframe. Use src or destinations for top-level navigation.

Rendering React content

Pass React children instead of src to render through an iframe portal. CSS media queries then use the iframe viewport, unlike a host-width <div>.

<DevicePreviewLab
  defaultDeviceId="pixel-10"
  portalStyles="body { margin: 0; font-family: system-ui; }"
>
  <YourResponsiveApplication />
</DevicePreviewLab>

Portal component closures still run in the host JavaScript realm. Read iframe modes and fidelity before choosing this mode.

Documentation

• Documentation guide index
• Public API and custom devices
• Iframe modes, routes, and bridge
• Environment scenarios and native limitations
• Theme customization
• Accessibility
• Vite, Next.js, and SSR integration
• Browser support
• Security policy and iframe guidance
• Device data and update policy
• Device skins and visual fidelity
• Release process
• Contributing, changelog, and MIT license

The repository also generates a searchable HTML reference site from the TSDoc comments on the public TypeScript API and includes every guide above in the same navigation:

npm run docs:build

Open site/index.html after the build. The generated site/ directory is intentionally ignored; source comments and Markdown remain authoritative. For live local navigation and search, run npm run docs:serve and open http://127.0.0.1:4176.

Acknowledgement

Flutter Device Preview demonstrated how valuable an integrated device-preview workflow can be and inspired the interaction category. This repository is an independent React/web implementation: it does not copy that project’s code, data, or assets.

Status

The first public release, 1.0.0, shipped on 2026-07-26; the changelog tracks the current version. No package publication is performed by ordinary CI, and a maintainer must explicitly publish a matching GitHub Release before the trusted-publishing workflow can run.