The call object and provider

The call object is the heart of every Daily app: it is the daily-js instance that joins rooms, sends media, and emits events. DailyProvider holds it and shares it with your component tree. In most apps, the provider creates and manages the call object for you.

Let DailyProvider create the call object

The simplest and recommended setup is to pass your room url (and any other factory options such as token or userName) directly to DailyProvider. The provider creates the call object, manages its lifecycle, and tears it down for you.

import { DailyProvider } from '@daily-co/daily-react';

function App() {
  return (
    <DailyProvider url="https://your-domain.daily.co/room-name">
      <Call />
    </DailyProvider>
  );
}

This is the right default for most apps: there is no instance to create, store, or clean up, and it is the hardest setup to get wrong.

The provider recreates the call object whenever a creation prop’s value changes (url, token, and so on), tearing down the current call and resetting all call and error state. These props are compared by value, so re-passing an equivalent object on each render is safe; only an actual value change triggers a rebuild, and nothing defers it while a call is in progress. Treat creation props as stable configuration for the duration of a call.

Create the call object yourself

Create the instance yourself only when you need direct control over it, for example to access it before the provider mounts, share it outside the provider tree, or create it conditionally. Use useCallObject, then pass it to the provider with the callObject prop:

import { DailyProvider, useCallObject } from '@daily-co/daily-react';

function App() {
  const callObject = useCallObject({
    options: {
      subscribeToTracksAutomatically: true,
    },
  });
  return (
    <DailyProvider callObject={callObject}>
      <Call />
    </DailyProvider>
  );
}

Use useCallObject rather than calling Daily.createCallObject() yourself. It deduplicates instances, which prevents the Duplicate DailyIframe instances are not allowed error that surfaces under React Strict Mode (where effects intentionally run twice in development).

To delay creation until some condition is met, pass shouldCreateInstance:

// roomUrl comes from your props, router, or state
const callObject = useCallObject({
  shouldCreateInstance: () => Boolean(roomUrl),
});

Access it anywhere with useDaily

Inside the provider, useDaily returns the same DailyCall instance. Use it for imperative actions that do not have a dedicated hook:

import { useDaily } from '@daily-co/daily-react';

function Controls() {
  const daily = useDaily();
  return (
    <>
      <button onClick={() => daily?.setLocalAudio(false)}>Mute me</button>
      <button onClick={() => daily?.setLocalVideo(false)}>Camera off</button>
    </>
  );
}

daily is null until the call object exists, so guard with optional chaining or an early return.

The call lifecycle

A custom call moves through the same lifecycle as any daily-js call. useMeetingState gives you the current stage reactively:

import { useMeetingState } from '@daily-co/daily-react';

function CallStatus() {
  const meetingState = useMeetingState();
  // 'new' | 'loading' | 'loaded' | 'joining-meeting'
  // | 'joined-meeting' | 'left-meeting' | 'error'
  return <span>Status: {meetingState}</span>;
}

Joining and leaving

There is no useJoin hook: joining is an imperative action, so call join() on the object from useDaily. A mount effect with a cleanup that calls leave() is the idiomatic pattern:

import { useEffect } from 'react';
import { useDaily } from '@daily-co/daily-react';

function Call({ roomUrl, token }) {
  const daily = useDaily();

  useEffect(() => {
    if (!daily) return;
    daily.join({ url: roomUrl, token });
    return () => {
      daily.leave();
    };
  }, [daily, roomUrl, token]);

  return null;
}

If you set url (and token) on DailyProvider as recommended above, the call object already has them, so you can call daily.join() with no arguments. Pass them to join() explicitly only when they are not already on the provider. The instance is reusable: after leave(), the meeting state becomes left-meeting and you can join() again.

Handling errors

useDailyError exposes the most recent fatal and nonfatal errors as state:

import { useDailyError } from '@daily-co/daily-react';

function ErrorBanner() {
  const { meetingError, nonFatalError } = useDailyError();
  if (!meetingError && !nonFatalError) return null;
  return <p role="alert">{meetingError?.errorMsg ?? nonFatalError?.errorMsg}</p>;
}

A fatal error ejects the participant from the meeting immediately. If you render UI from meetingError, do not destroy the call object (or change DailyProvider’s creation props, which destroys it internally) until you no longer need the error state.

Embedding Prebuilt instead of a custom UI

If you want Daily’s ready-made UI, create a Prebuilt iframe with useCallFrame and pass it to the same provider:

import { DailyProvider, useCallFrame } from '@daily-co/daily-react';
import { useRef } from 'react';

function PrebuiltApp() {
  const ref = useRef(null);
  const callFrame = useCallFrame({ parentElRef: ref });
  return (
    <DailyProvider callObject={callFrame}>
      <div ref={ref} style={{ height: '100vh' }} />
    </DailyProvider>
  );
}

An iframe runs in a separate secure context, so track-level data is not available across the boundary. Hooks that read meeting and participant state still work, but media hooks like useMediaTrack will not return tracks. For full control over media, use a call object instead.

Getting Started

Core Concepts

Building Call Features

The call object and provider

Let DailyProvider create the call object

Create the call object yourself

Access it anywhere with useDaily

The call lifecycle

Joining and leaving

Handling errors

Embedding Prebuilt instead of a custom UI

Next steps

Working with participants

Rendering media

​Let DailyProvider create the call object

​Create the call object yourself

​Access it anywhere with useDaily

​The call lifecycle

​Joining and leaving

​Handling errors

​Embedding Prebuilt instead of a custom UI

​Next steps

Working with participants

Rendering media

Let DailyProvider create the call object

Create the call object yourself

Access it anywhere with useDaily

The call lifecycle

Joining and leaving

Handling errors

Embedding Prebuilt instead of a custom UI

Next steps