uppy/docs/sources/webcam.mdx

---
sidebar_position: 1
slug: /webcam
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

import UppyCdnExample from '/src/components/UppyCdnExample';

# Webcam

The `@uppy/webcam` plugin lets you take photos and record videos with a built-in
camera on desktop and mobile devices.

:::tip

[Try out the live example](/examples) or take it for a spin in
[StackBlitz](https://stackblitz.com/edit/vitejs-vite-zaqyaf?file=main.js).

:::

## When should I use it?

When you want your users to able to use their camera. This plugin is published
separately but made specifically for the [Dashboard](/docs/dashboard). You can
technically use it without it, but it’s not officially supported.

## Install

<Tabs>
  <TabItem value="npm" label="NPM" default>

```shell
npm install @uppy/webcam
```

  </TabItem>

  <TabItem value="yarn" label="Yarn">

```shell
yarn add @uppy/webcam
```

  </TabItem>

  <TabItem value="cdn" label="CDN">
    <UppyCdnExample>
      {`
        import { Uppy, Dashboard, Webcam } from "{{UPPY_JS_URL}}"
        const uppy = new Uppy()
        uppy.use(Dashboard, { inline: true, target: 'body' })
        uppy.use(Webcam)
      `}
    </UppyCdnExample>
  </TabItem>
</Tabs>

## Use

:::note

To use the Webcam plugin in Chrome,
[your site must be served over https](https://developers.google.com/web/updates/2015/10/chrome-47-webrtc#public_service_announcements).
This restriction does not apply on `localhost`, so you don’t have to jump
through many hoops during development.

:::

```js {3,7,11} showLineNumbers
import Uppy from '@uppy/core';
import Dashboard from '@uppy/dashboard';
import Webcam from '@uppy/webcam';

import '@uppy/core/dist/style.min.css';
import '@uppy/dashboard/dist/style.min.css';
import '@uppy/webcam/dist/style.min.css';

new Uppy().use(Dashboard, { inline: true, target: 'body' }).use(Webcam);
```

## API

### Options

#### `id`

A unique identifier for this plugin (`string`, default: `'Webcam'`).

#### `target`

DOM element, CSS selector, or plugin to place the drag and drop area into
(`string`, `Element`, `Function`, or `UIPlugin`, default:
[`Dashboard`](/docs/dashboard)).

#### `countdown`

When taking a picture: the amount of seconds to wait before actually taking a
snapshot (`boolean`, default: `false`).

If set to `false` or 0, the snapshot is taken right away. This also shows a
`Smile!` message through the [Informer](/docs/informer) before the picture is
taken.

#### `onBeforeSnapshot`

A hook function to call before a snapshot is taken (`Function`, default:
`Promise.resolve`).

The Webcam plugin will wait for the returned Promise to resolve before taking
the snapshot. This can be used to carry out variations on the `countdown` option
for example.

#### `modes`

The types of recording modes to allow (`Array`, default: `[]`).

- `video-audio` - Record a video file, capturing both audio and video.
- `video-only` - Record a video file with the webcam, but don’t record audio.
- `audio-only` - Record an audio file with the user’s microphone.
- `picture` - Take a picture with the webcam.

By default, all modes are allowed, and the Webcam plugin will show controls for
recording video as well as taking pictures.

#### `mirror`

Configures whether to mirror preview image from the camera (`boolean`, default:
`true`).

This option is useful when taking a selfie with a front camera: when you wave
your right hand, you will see your hand on the right on the preview screen, like
in the mirror. But when you actually take a picture, it will not be mirrored.
This is how smartphone selfie cameras behave.

#### `videoConstraints`

Configure the [`MediaTrackConstraints`][] (`Object`, default: `{}`).

You can specify acceptable ranges for the resolution of the video stream using
the [`aspectRatio`][], [`width`][], and [`height`][] properties. Each property
takes an object with `{ min, ideal, max }` properties. For example, use
`width: { min: 720, max: 1920, ideal: 1920 }` to allow any width between 720 and
1920 pixels wide, while preferring the highest resolution.

Devices sometimes have several cameras, front and back, for example.
[`facingMode`][] lets you specify which should be used:

- `user`: The video source is facing toward the user; this includes, for
  example, the front-facing camera on a smartphone.
- `environment`: The video source is facing away from the user, thereby viewing
  their environment. This is the back camera on a smartphone.
- `left`: The video source is facing toward the user but to their left, such as
  a camera aimed toward the user but over their left shoulder.
- `right`: The video source is facing toward the user but to their right, such
  as a camera aimed toward the user but over their right shoulder.

For a full list of available properties, check out MDN documentation for
[`MediaTrackConstraints`][].

[`mediatrackconstraints`]:
	https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints#Properties_of_video_tracks
[`aspectratio`]:
	https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/aspectRatio
[`width`]:
	https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/width
[`height`]:
	https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/height
[`facingmode`]:
	https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/facingMode

#### `showVideoSourceDropdown`

Configures whether to show a dropdown which enables to choose the video device
to use (`boolean`, default: `false`).

This option will have priority over `facingMode` if enabled.

#### `showRecordingLength`

Configures whether to show the length of the recording while the recording is in
progress (`boolean`, default: `false`).

#### `preferredVideoMimeType`

Set the preferred mime type for video recordings, for example `'video/webm'`
(`string`, default: `null`).

If the browser supports the given mime type, the video will be recorded in this
format. If the browser does not support it, it will use the browser default. If
no preferred video mime type is given, the Webcam plugin will prefer types
listed in the [`allowedFileTypes` restriction](/docs/uppy/#restrictions), if
any.

#### `preferredImageMimeType`

Set the preferred mime type for images, for example `'image/png'` (`string`,
default: `image/jpeg`).

If the browser supports rendering the given mime type, the image will be stored
in this format. Else `image/jpeg` is used by default. If no preferred image mime
type is given, the Webcam plugin will prefer types listed in the
[`allowedFileTypes` restriction](/docs/uppy/#restrictions), if any.

#### `mobileNativeCamera`

Replaces Uppy’s custom camera UI on mobile and tablet with the native device
camera (`Function: boolean` or `boolean`, default: `isMobile()`).

This will show the “Take Picture” and / or “Record Video” buttons, which ones
show depends on the [`modes`](#modes) option.

You can set a boolean to forcefully enable / disable this feature, or a function
which returns a boolean. By default we use the
[`is-mobile`](https://github.com/juliangruber/is-mobile) package.

#### `locale`

```js
export default {
	strings: {
		pluginNameCamera: 'Camera',
		noCameraTitle: 'Camera Not Available',
		noCameraDescription:
			'In order to take pictures or record video, please connect a camera device',
		recordingStoppedMaxSize:
			'Recording stopped because the file size is about to exceed the limit',
		submitRecordedFile: 'Submit recorded file',
		discardRecordedFile: 'Discard recorded file',
		// Shown before a picture is taken when the `countdown` option is set.
		smile: 'Smile!',
		// Used as the label for the button that takes a picture.
		// This is not visibly rendered but is picked up by screen readers.
		takePicture: 'Take a picture',
		// Used as the label for the button that starts a video recording.
		// This is not visibly rendered but is picked up by screen readers.
		startRecording: 'Begin video recording',
		// Used as the label for the button that stops a video recording.
		// This is not visibly rendered but is picked up by screen readers.
		stopRecording: 'Stop video recording',
		// Used as the label for the recording length counter. See the showRecordingLength option.
		// This is not visibly rendered but is picked up by screen readers.
		recordingLength: 'Recording length %{recording_length}',
		// Title on the “allow access” screen
		allowAccessTitle: 'Please allow access to your camera',
		// Description on the “allow access” screen
		allowAccessDescription:
			'In order to take pictures or record video with your camera, please allow camera access for this site.',
	},
};
```