Skip to Content
Mux Docs: Home
Welcome to the new Mux Docs.
The old version is still available here

Naming your participants

Set and get participant display names

In this guide:

Understand display names

Set your display name while joining

Update your display name

Retrieve display names from participants

Listen for display names changes

Understand display names

A participant can set a display name for themselves at join time, or at any time while connected to space. The initial display name, as well as any updates to the display name, will be available to other participants in the space, and reflected in any broadcasts created from this space.

The display name must be a string and must not be longer than 64 characters. The display name of a given participant may not be changed more than once every 10 seconds.

Set your display name while joining

Refer to the web SDK documentation to learn more about the API.

Before joining, a participant may pass a display name to the created space. This will set their display name immediately at join time.

import { Space } from "@mux/spaces-web";

// Initialize Space, joining with a display name already set 
const space = new Space(JWT, {
  displayName: "Alice 🚀!!",
});

const localParticipant = await space.join();

Update your display name

While connected, a participant can set their display name up to once every 10 seconds.

import { Space } from "@mux/spaces-web";

// Initialize Space
const space = new Space(JWT);
const localParticipant = await space.join();

// Update the local participant's display name. 
// If successful, a SpaceEvent.ParticipantDisplayNameChanged event is emitted to
// the Space and a ParticipantEvent.DisplayNameChanged event is emitted to the
// LocalParticipant.
try {
  localParticipant.setDisplayName("Alice 🚀!!");
} catch (
  // Handle errors
)

Retrieve display names from participants

A participant's display name is always accessible as a field on the participant. If the participant has not set a display name, the string will be empty.

import { Space, SpaceEvent } from "@mux/spaces-web";

const space = new Space(JWT, {
  displayName: "Alice 🚀!!",
});
const localParticipant = await space.join();

// Get display name of the local participant
const localDisplayName = localParticipant.displayName;

space.on(SpaceEvent.ParticipantJoined, (participant) => {
  // Get display names of the remote participant, if it's been set
  let displayName = participant.displayName ? participant.displayName : "default name";
});

Listen for display names changes

Developers can listen to the Space or the participant to be notified of any changes to a participant's display name.

import { Space, SpaceEvent, ParticipantEvent } from "@mux/spaces-web";

const space = new Space(JWT);

// Get the initial display name and listen on the sender for 
// ParticipantEvent.DisplayNameChanged updates.
space.on(SpaceEvent.ParticipantJoined, (participant) => {
  // Handle initial display name, if it's been set
  let displayName = participant.displayName ? participant.displayName : "default name";

  // The event handler has no arguments. The displayName field of the
  // participant object will reflect its changed value.
  participant.on(ParticipantEvent.DisplayNameChanged, () => {
    // Handle display name change
    displayName = participant.displayName;
  })
});

// Listen to the Space for a SpaceEvent.ParticipantDisplayNameChanged event
// The argument in the event handler is the sender whose display name has
// changed.
space.on(SpaceEvent.ParticipantDisplayNameChanged, (participant) => {
  // Handle display name change
  const displayName = participant.displayName;
});

// Join the space. It's advised to set up the display name handlers first so
// that the initial display names of existing participants are handled in their
// SpaceEvent.ParticipantJoined events.
const localParticipant = await space.join();

Was this page helpful?