Audio player

01Preview

Change the controls to try every supported option. The docs ship no audio files, so this preview simulates playback with props; in an app you pass src.

import { AudioPlayer } from '@nuton/ui'

<AudioPlayer
  title="Introduction to Design Principles"
  src="/podcasts/design-principles-1.mp3"
  subtitle="The Design of Everyday Things · Episode 2"
  onClose={closePlayer}
/>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens

npm install @nuton/ui @nuton/tokens

yarn add @nuton/ui @nuton/tokens

Peer dependencies: react and react-dom 18 or later. The icons come from @remixicon/react, a dependency of @nuton/ui. The speed menu uses the Dropdown menu (Radix).

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

03Usage

import { AudioPlayer } from '@nuton/ui'

export function EpisodePlayer({ episode, onClose }) {
  return (
    <AudioPlayer
      title={episode.title}
      src={episode.audioUrl}
      onClose={onClose}
    />
  )
}

• Pass src and the player renders its own <audio> element and reads time, duration and state from it. Use audioRef to reach the element.
• Without src, drive it with props: playing, currentTime, duration, and the onPlayingChange, onSeek and onPlaybackRateChange callbacks. Use this for a shared or native player.
• Show one player at a time, fixed near the bottom of the Podcast tab, and keep it open while people browse episodes.
• Use EpisodeCard inside an EpisodeList for the episodes. Each card's buttons include the episode title in their names.
• Pass onClose to show the close button. Stop playback when the player closes.

04Variants and sizes

The dock is the player. The earlier floating pill remains as layout="pill" for existing uses: it has two surfaces, and Figma names them after the page theme (Property 1=Light is the dark pill) while code names them after the pill itself.

Appearance

Dock (the default)

The dock is the player (layout="dock" is the default): it is the bar for the bottom edge of an app. It follows the theme (light, dark or the device setting): full width, square corners, always the near-black surface, and a thin line along its top. It is compact by default (cover, title, waveform, time, play, expand, close) and grows upward when expanded (the waveform full width with both times, speed, back and forward, play, next, minimize). It is one player with two layers of controls, so expanding and minimizing never interrupt playback. Put it where it docks (a flex child under the content, not an overlay) and the content above it simply gets shorter. The waveform is the seek bar: pointer, arrow, Page and Home/End keys, and a spoken value. Pass peaks for a real waveform; without it a shape that suggests speech is drawn.

<AudioPlayer
  layout="dock"
  title="Affordances and signifiers"
  subtitle="The Design of Everyday Things · Episode 2"
  src={url}
  onNext={nextEpisode}
  onClose={closePlayer}
/>

<AudioPlayer layout="dock" defaultExpanded title="Affordances and signifiers" src={url} onNext={nextEpisode} onClose={closePlayer} />

Pill (earlier design, kept for existing uses)

The floating pill with the two surfaces below is the earlier design. New work uses the dock; the pill stays as layout="pill" only so existing screens keep working.

<AudioPlayer layout="pill" title="Introduction to Design Principles" src={url} onClose={closePlayer} />

<AudioPlayer layout="pill" appearance="light" title="Introduction to Design Principles" src={url} onClose={closePlayer} />

Episode card

<EpisodeList aria-label="Episodes">
  <EpisodeCard
    number={1}
    title="Introduction to Design Principles"
    description="The core principles behind products, systems and experiences."
    duration={5340}
    downloadHref="/podcasts/design-1.mp3"
    onPlay={playEpisode}
  />
</EpisodeList>

Sizes

Values from the component CSS, which follows Figma's geometry (Control center 604:35881, episode cards 594:20678). When the player is narrower than 520px, title and slider move above the controls and the pill becomes a rounded card (code-only).

05States and interactions

Episode states

Figma has three types. The status comes from progress unless you set status: nothing heard is new, part heard is in progress (time left and a ring), all heard is completed. Pass playing to the episode that is playing now.

<EpisodeCard number={1} title="…" duration={5340} />                  // new: play icon, "1h 29m"
<EpisodeCard number={2} title="…" duration={5340} progress={1620} />  // in progress: rhythm icon, "1h 2m left", ring
<EpisodeCard number={3} title="…" duration={5340} progress={5340} />  // completed: reset icon, "1h 29m"

State tokens

Set on .nu-audio-player and .nu-episode-card. Override them on a wrapper only for a documented exception.

06Composition examples

Podcast tab

Episode cards start an episode; the player appears below and keeps playing while people scroll. Pressing the playing episode's button pauses it. Each episode resumes where it stopped.

const [current, setCurrent] = useState<Episode | null>(null)

<EpisodeList aria-label="Design Principles podcast">
  {episodes.map((e) => (
    <EpisodeCard
      key={e.id}
      number={e.number}
      title={e.title}
      description={e.description}
      duration={e.duration}
      progress={e.secondsHeard}
      playing={current?.id === e.id && playing}
      onPlay={() => play(e)}
      downloadHref={e.audioUrl}
    />
  ))}
</EpisodeList>

{current ? (
  <AudioPlayer
    title={`${current.number}. ${current.title}`}
    src={current.audioUrl}
    playing={playing}
    onPlayingChange={setPlaying}
    onTimeUpdate={(t) => saveProgress(current.id, t)}
    onClose={() => setCurrent(null)}
  />
) : null}

Localised labels

Every string is a labels entry. The time strings are functions, so you can say times naturally in each language.

<AudioPlayer
  title="Introducción a los principios de diseño"
  src={url}
  appearance="light"
  labels={{
    player: 'Reproductor de audio',
    play: 'Reproducir',
    pause: 'Pausa',
    back: (s) => `Retroceder ${s} segundos`,
    forward: (s) => `Avanzar ${s} segundos`,
    speed: 'Velocidad',
    seek: 'Posición',
    position: (c, d) => `${Math.floor(c / 60)} min ${Math.floor(c % 60)} s de ${Math.floor(d / 60)} min`,
  }}
/>

07API reference

AudioPlayer props

EpisodeCard props

EpisodeList props

Helpers

formatClockTime (“1:02:23”), formatSpokenTime (“1 hour 2 minutes 23 seconds”), formatShortDuration (“1h 29m”), getEpisodeStatus, AUDIO_PLAYER_LABELS, AUDIO_PLAYER_RATES and EPISODE_CARD_LABELS are exported for building your own labels.

Styling hooks

The player renders .nu-audio-player (with data-appearance and data-playing), __bar, __speed, __skip, __play, __title, __seek (a Slider with .nu-slider__* parts), __times and __close. Cards render .nu-episode-card (with data-status) in .nu-episode-list. Use the --nu-audio-player-* and --nu-episode-card-* tokens to override.

Accessibility

You must: give every player a meaningful title; stop playback when the player closes; never autoplay without a user action; and pass translated labels in other languages, including the spoken position text.

Figma mapping

08Guidelines and related components

Do and don't

Common mistakes

• Starting playback on page load. Wait for the user to press play.
• Keeping audio playing after the close button is pressed.
• Translating the button names but not position, so the slider still speaks English times.
• Passing both src and currentTime: with src, the position comes from the element.

Related components

• ProgressProgress bars and rings that aren’t interactive.
• Dropdown menuThe menu behind the speed button.
• ButtonSingle actions, such as a play button for a short clip.
• SourcesCitations and source files next to lesson content.