Skip to content
Design System
GitHub

Robot model

v0.24.2Beta

A robot's pose in 3D from its URDF and live joint values (ROS sensor_msgs/JointState), for monitoring: neutral greys from the theme, a ground grid and axes named in words; highlighted joints in a status colour with a callout naming them; orbit, pan and zoom by pointer and keys; loading, error with the failing file, empty, stale and no-WebGL states in words. The kit's one three.js item.

Robot model default

Install
npx shadcn add @syncrobotic/robot-model

Also installs: three@^0.187.0, urdf-loader@^0.13.1, lucide-react, @syncrobotic/cn, @syncrobotic/button, @syncrobotic/button-group, @syncrobotic/spinner, @syncrobotic/skeleton

Overview

When to use

  • An arm's pose on its robot page, from /joint_states.
  • Showing which joint is near its limit, or the pose a robot stopped in, beside the alarm that says so.
  • Checking a robot's description: that the URDF loads and its joints turn the right way.

Use something else

  • Where robots are on a site: Robot map.
  • What the robot sees: Camera feed.
  • A few joint values to read at a glance: data-pieces or a table, which need no 3D.

More examples

States and real uses. Each example is also a Storybook story and a visual regression test.

Robot model animated

Robot model highlighted joint

Robot model loading

Robot model error

Robot model stale

Robot model text fallback

Robot model empty

Usage rules

  • For watching a robot's pose: an arm at work, a joint near its limit, the pose a fault stopped it in. It shows the robot and never moves it; jogging and teleoperation are other controls.
  • Pass joints as ROS sends them (radians, metres for prismatic joints); jointStateToRecord turns a sensor_msgs/JointState into the record. A value past a limit is drawn where it is, not clamped: the view shows what the robot reports.
  • Highlight only what needs someone (a joint near its limit, a link in fault), a handful at most. The link is drawn in the warning colour (highlightStatus="danger" for a fault) and a callout names the joint with its value and limits, so it never rests on colour alone.
  • Pass staleAfterMs whenever the joints come from a live topic (1 s for /joint_states at 10 Hz or more), and updatedAt from the message's stamp: the last pose stays, dimmed, with when it arrived. Without updatedAt only a change of value counts as an update, so a robot holding still goes stale.
  • Serve meshes from your own origin: packages maps each package:// name to a URL, meshBaseUrl is the folder for the rest. STL and COLLADA load; a file that fails is named in the error.
  • One view per screen. Each view holds a WebGL context and browsers allow only a few; for a fleet, list the robots and open one view for the robot chosen.
  • Load it lazily (next/dynamic or React.lazy): three.js is large, and only the screens that show a robot model should download it.

Changelog

  • 0.24.22026-11-21Mimic joints follow the joint they mimic with limits ignored on every joint, and the driving joint's value wins over a mimic's own whatever the order; a mimic joint can be highlighted by name (RobotModelInfo.mimics). Planar and floating joints take [x, y, θ] and [x, y, z, roll, pitch, yaw] and are written per component in mm and ° (new poseValue label, jointValueWords, jointValueOf); one number no longer leaves their other components undefined.
  • 0.24.12026-11-21Stale now follows the joint values (or updatedAt), not the joints object: an inline record no longer keeps the view fresh, or flips it in and out of Stale and announces it on every render; without updatedAt a robot holding still goes stale. A view rebuilt after a lost context no longer stays on “Restoring the 3D view…”, and a context not back within 5 s shows an error with Load again (new label contextFailed). An empty URDF file is an error instead of an endless load; meshes that arrive after the view is gone are freed; mesh paths with a query string load; a theme set on any ancestor is followed; a theme colour that does not parse no longer takes the previous one.
  • 0.24.02026-11-21First release.

How to upgrade