Matrix Power Levels#

Matrix power levels are integers assigned per-user in a room, controlling what actions a member can take. They are stored in the m.room.power_levels state event (state key ""). The standard tiers are 0 (default/restricted), 50 (moderator), and 100 (admin), but any integer is valid.

SDK Data Model#

In matrix-js-sdk, power level state is owned by RoomState and propagated to individual RoomMember objects.

• IPowerLevelsContent — the TypeScript interface for m.room.power_levels content, defining users, events, users_default, events_default, state_default, ban, kick, invite, redact, and notifications 1.
• RoomMember.powerLevel — the resolved integer level for the member; defaults to 0 2. Set via setPowerLevelEvent(), which reads users[userId] first, then users_default, then falls back to 0.
• RoomMember.powerLevelNorm — a 0–100 normalised value relative to the highest level in the room 3, used for visual ordering.
• RoomStateEvent.Members is emitted when a member's power level changes 4, but only if the level actually changed — to avoid unnecessary re-renders in large rooms.

When a new member joins, RoomState.updateMember() immediately applies the existing m.room.power_levels event to that member.

Permission Checks#

RoomState exposes several helpers built on the power level event:

The core logic lives in maySendEventOfType(). When a m.room.power_levels event exists, state_default falls back to 50 if not explicitly set 5 — matching the Matrix spec convention that state events require moderator-level permission by default. events_default falls back to 0 6.

Spec Compliance Gap: Missing Power Levels Event#

When no m.room.power_levels event exists, maySendEventOfType() initialises stateDefault, eventsDefault, and powerLevel all to 0 7 and skips the entire conditional block. This means every user (at power level 0) passes the state_default = 0 check and can send any event, including state events. The Matrix spec states that if state_default is absent from an existing power levels event it should default to 50; but the SDK only applies that 50 fallback when the event exists — not when the event itself is missing. Rooms created without a m.room.power_levels event are therefore treated as fully open, which is a known area of spec divergence.

UI Role Label Mapping (matrix-react-sdk)#

Element Web maps numeric power levels to human-readable labels in src/Roles.ts:

• levelRoleMap(usersDefault) — returns a record keyed by level number 8:
  • undefined → "Default" (i18n key power_level|default)
  • 0 → "Restricted"
  • usersDefault → "Default"
  • 50 → "Moderator"
  • 100 → "Admin"
• textualPowerLevel(level, usersDefault) — looks up a level in the map; falls back to "Custom (N)" for any numeric level not in the map 9.

These functions are consumed by:

• PowerSelector — the dropdown used in room settings to change permission requirements.
• UserInfo — the right-panel user detail view, which calls textualPowerLevel(powerLevel, powerLevelUsersDefault) to show a role description.

Member List Badges#

MemberTile renders a visual badge for Admin (≥ 100) and Moderator (≥ 50) using a powerStatusMap 10. It finds the nearest threshold the member's level meets, so a user at level 75 gets the Moderator badge. The badge label text is resolved from the PowerLabel map in EntityTile.tsx, which translates PowerStatus.Admin and PowerStatus.Moderator to i18n strings.

Room Settings: Roles & Permissions Tab#

RolesRoomSettingsTab is the primary UI for viewing and editing power levels. It:

1. Reads plContent from room.currentState.getStateEvents(EventType.RoomPowerLevels, "") and falls back to {} if absent 11.
2. Populates default levels for well-known event types via populateDefaultPlEvents() 12, using state_default (default 50) and events_default (default 0) from the current event.
3. Sends a new m.room.power_levels state event on change 13.

PowerLevelSelector 14 lists privileged (above users_default) and muted (below users_default) users separately 15.

Key Source Files#