js-camera

Zero-dependency camera element for the web. Drop in <js-camera>, capture frames, and ship.

Live Demo

• Web Components V1 — works with React, Vue, Svelte, or vanilla
• Capture as PNG / JPEG / WebP with resize, crop, and fit options
• Pinch-to-zoom on touch devices
• Built-in controls (play/pause, capture, face-switch) or go fully programmatic
• Front / back camera switching and device selection
• Zero dependencies, ~10 KB gzipped

npm install js-camera

3 Lines to Camera

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">

<js-camera autoplay facing="back" controls></js-camera>

import 'js-camera';

That's it. Play/pause, capture, face-switch — all built in. Fills the viewport by default. The viewport meta prevents the browser from hijacking pinch-to-zoom.

Custom Size

js-camera {
  width: 400px;
  height: 300px;
}

Go Deeper

Drop the controls attribute and take full control.

import 'js-camera';

const camera = document.querySelector('js-camera');

// Open rear camera at Full HD
await camera.open({ facingMode: 'back', width: 1920, height: 1080 });

// Capture
const png = camera.capture();
const jpeg = camera.capture({ format: 'image/jpeg', width: 640, height: 480, fit: 'cover' });
const cropped = camera.capture({ extract: { x: 100, y: 50, width: 200, height: 200 } });

// Playback
camera.pause();
camera.play();

// Done
camera.close();

Create on the Fly

import Camera from 'js-camera';

const camera = Camera.createElement();
document.body.appendChild(camera);
await camera.open({ facingMode: 'front' });

Listen

camera
  .on('opened',   () => console.log('Ready'))
  .on('captured', (e) => upload(e.detail.capture))
  .on('paused',   () => console.log('Paused'))
  .on('played',   () => console.log('Resumed'));

Event	Fires when	event.detail
opened	Stream is ready	—
captured	Frame captured via built-in button	.capture — data URL
paused	Playback paused	—
played	Playback resumed	—

API

HTML Attributes

Attribute	Description	Default
autoplay	Open camera on DOM insertion	—
facing	"front" or "back" (used with autoplay)	"back"
width	Desired resolution width (px)	device default
height	Desired resolution height (px)	device default
controls	Show built-in UI	—

Static Methods

Method	Returns	Description
Camera.define()	typeof Camera	Register <js-camera>. Auto-called on import.
Camera.createElement()	Camera	Create a new element. Calls define() if needed.

Properties (read-only)

Property	Type	Description
state	'open' | 'loading' | 'close'	Lifecycle state
opened	boolean	Stream is active
paused	boolean	Playback is paused
facingMode	'front' | 'back' | undefined	Current direction
deviceId	string | undefined	Active camera device ID
resolution	{ width, height }	Actual hardware resolution
track	MediaStreamTrack | undefined	Active video track
zoom	number	Current zoom level (1 = no zoom)

Methods

open(options?): Promise<MediaTrackSettings>

Opens the camera. Re-opens if already active. Throws DOMException on denial or unavailable device.

Option	Type	Default	Note
facingMode	'front' | 'back'	'front'	Ignored when deviceId is set
width	number	—	Falls back to HTML attribute
height	number	—	Falls back to HTML attribute
deviceId	string	—	Target a specific camera

waitOpen(): Promise<void>

Resolves when the camera finishes opening. Instant if not loading.

close()

Stops the stream and releases all resources.

play(): Promise<void>

Resumes from pause.

pause()

Freezes the current frame.

resetZoom()

Resets zoom level to 1. Pinch-to-zoom is built in — use two fingers on touch devices.

capture(options?): string

Returns a data URL of the current frame.

Option	Type	Default	Note
width	number	—	Omit one to keep aspect ratio
height	number	—	Omit one to keep aspect ratio
fit	'cover' | 'contain' | 'fill'	'fill'	Same as CSS object-fit
format	string	'image/png'	'image/jpeg', 'image/webp', etc.
extract	{ x, y, width, height }	—	Crop region in CSS pixels

queryPermission(): Promise<PermissionState | undefined>

Returns 'granted', 'denied', 'prompt', or undefined if unsupported.

revokePermission(): Promise<void>

Revokes camera permission. Not supported in all browsers.

getDevices(): Promise<Array<{ deviceId, label }>>

Lists available cameras. Requests temporary access if needed.

on(type, listener, options?): Camera

Adds a listener. Returns this for chaining. Pass { once: true } to auto-remove.

off(type, listener): Camera

Removes a listener. Returns this for chaining.

Types

import Camera, { type CameraOpenOptions, type CaptureOptions } from 'js-camera';

interface CameraOpenOptions {
  facingMode?: 'front' | 'back';  // default: 'front'
  width?: number;
  height?: number;
  deviceId?: string;
}

interface CaptureOptions {
  width?: number;
  height?: number;
  extract?: { x: number; y: number; width: number; height: number };
  fit?: 'cover' | 'contain' | 'fill';  // default: 'fill'
  format?: string;                       // default: 'image/png'
}

Browser Support

Custom Elements V1 + getUserMedia

Changelog

CHANGELOG.md

Author

shumatsumonobu — GitHub / X / Facebook

License

MIT