react-stl-model-viewer

A reusable React component for inspecting STL meshes in the browser. It supports loading from remote URLs or uploaded files, face highlighting, orbit controls, and a face-selection workflow that flattens the chosen triangle onto the build plane while reporting the resulting orientation.

Features

• Drop-in <StlModelViewer /> component with a dark, modern presentation
• Load STL files from modelUrl or a user-provided File/Blob
• Hover feedback and selectable faces rendered with vertex colours
• Face selection rotates the object so the selected triangle lies flat on the ground plane
• Orientation callback returns quaternion, Euler angles, and translation offsets
• Visible bounding-box helper and opt-in face selection toggle
• Optional grid/axes helpers and fully configurable colours

Installation

npm install react-stl-model-viewer three @react-three/fiber @react-three/drei

All runtime dependencies (react, react-dom, three, @react-three/fiber, and @react-three/drei) are declared as peer dependencies so your application controls the versions.

Usage

import { useState } from 'react'
import { StlModelViewer, type FaceSelectionEvent } from 'react-stl-model-viewer'

const MODEL_URL =
  'https://raw.githubusercontent.com/mrdoob/three.js/dev/examples/models/stl/binary/pr2_head_pan.stl'

export function Example() {
  const [orientation, setOrientation] = useState<FaceSelectionEvent['orientation'] | null>(null)

  return (
    <div style={{ width: '640px', height: '480px' }}>
      <StlModelViewer
        modelUrl={MODEL_URL}
        onFaceSelect={(event) => setOrientation(event.orientation)}
      />
      {orientation ? (
        <pre>{JSON.stringify(orientation, null, 2)}</pre>
      ) : (
        <p>Select a face to receive orientation data.</p>
      )}
    </div>
  )
}

Component Props

| Prop | Type | Description | | ---- | ---- | ----------- | | modelUrl | string | Remote URL to an STL asset. Ignored when file is provided. | | file | File | Blob | Local STL file source (object URL managed internally). | | baseColor | string | Hex colour for unselected faces. Defaults to #d1d5db. | | highlightColor | string | Hex colour used while hovering a face. Defaults to #f97316. | | backgroundColor | string | Renderer background colour. Defaults to #0b1120. | | orbitControls | boolean | Toggle orbit controls (defaults to true). | | showGrid | boolean | Show or hide the ground grid helper (defaults to true). | | showAxes | boolean | Show or hide an axes helper (defaults to false). | | enableFaceSelection | boolean | Disable to turn off hover highlighting and face alignment (defaults to true). | | modelUpAxis | 'x' | 'y' | 'z' | '-x' | '-y' | '-z' | Which axis represents "up" in the STL file. Defaults to 'y'. | | initialRotation | [number, number, number] | Optional initial rotation Euler angles [x, y, z] to apply before centering/grounding. | | onFaceSelect | (event: FaceSelectionEvent) => void | Invoked when a face is clicked and flattened. | | onLoad | (info: { boundingBox }) => void | Called once the STL geometry loads, returning min/max/size vectors. |

FaceSelectionEvent exposes the selected face index, the world-space normal before rotation, and the orientation snapshot (quaternion, Euler angles in radians, and position).

Demos

The repository ships with a couple of ready-to-run demo components inside src/examples/:

• BasicViewer – loads a remote STL and reports orientation snapshots after face selection.
• InteractiveControls – showcases toggles for grid/axes/orbit controls and swaps between ASCII/Binary STL sources.
• FileUploadViewer – drag-and-drop uploader that previews a local STL.

These examples are plain React components that you can render in any host app. They are also handy references when integrating the package into your own design tools.

Development

• npm run dev – playground demo with hot reload (src/App.tsx)
• npm run build – bundles the package (ESM + CJS) and emits TypeScript declarations
• npm run lint – ESLint with type-aware rules

The dist/ directory contains the publishable artifacts after a successful build.