Skip to main content

Interface: MediaCustomAction

Defined in: packages/media-session/src/specs/media-session.nitro.ts:688

A custom action: a button with no built-in meaning.

Android only, by platform ceiling​

Android draws these as extra CommandButtons in the notification's overflow and grants them as SessionCommands so third-party controllers can invoke them; presses arrive at MediaSessionHandlers.customAction.

iOS has no surface for them and no way to gain one. MPRemoteCommandCenter's command set is fixed and closed — an app cannot add a command, and nothing in the set carries an app-defined identifier (the full list is enumerated on MediaCapability's skipToQueueItem). The three commands that look adjacent are not: likeCommand, dislikeCommand and bookmarkCommand are MPFeedbackCommands with fixed system semantics and system-drawn heart/thumb icons, and ratingCommand is a star rating (developer.apple.com/documentation/mediaplayer/mpremotecommandcenter, read 2026-08-16). Re-purposing one of them would draw the user a heart for "Add to playlist", and a wrong button is worse than a missing one.

So on iOS this array is accepted, carried, and renders nothing — customAction is never invoked from an iOS remote surface. Your own UI can still call the handler directly, which is what iOS apps do for this.

Properties​

icon?​

optional icon?: string;

Defined in: packages/media-session/src/specs/media-session.nitro.ts:694

Android drawable resource name. Ignored on iOS (no such surface).

name​

name: string;

Defined in: packages/media-session/src/specs/media-session.nitro.ts:690

Opaque identifier handed back to the JS handler's customAction.

title​

title: string;

Defined in: packages/media-session/src/specs/media-session.nitro.ts:692

User-visible label. Rendered on Android only; see the interface docs.