Quick Start

Get a working player in under 5 minutes.

Prerequisites

A React project with shadcn/ui initialized. If you don't have one:

npx shadcn@latest init

Option A: Start with a Block

The fastest path — install a complete, ready-to-use player:

npx shadcn add @limeplay/video-player

This gives you a full-featured video player with playback controls, volume, timeline, captions, and more. Customize it from your components/ directory. For more details, see the video player documentation.

Option B: Build from Scratch

Create the media runtime

Install the core provider and the features you need:

npx shadcn add @limeplay/media-provider @limeplay/use-player @limeplay/use-playback @limeplay/use-volume @limeplay/use-timeline @limeplay/use-playlist @limeplay/use-asset @limeplay/use-playback-source

Create a lib/media.ts file that composes your features:

lib/media.ts

"use client"

import { mediaFeature } from "@/hooks/limeplay/use-media"
import { assetFeature } from "@/hooks/limeplay/use-asset"
import { playerFeature } from "@/hooks/limeplay/use-player"
import { playbackFeature } from "@/hooks/limeplay/use-playback"
import { playlistFeature } from "@/hooks/limeplay/use-playlist"
import { volumeFeature } from "@/hooks/limeplay/use-volume"
import { timelineFeature } from "@/hooks/limeplay/use-timeline"
import { createMediaKit } from "@/components/limeplay/media-provider"

export const media = createMediaKit({
  features: [
    mediaFeature(),
    playerFeature(),
    playbackFeature(),
    playlistFeature(),
    assetFeature(),
    volumeFeature(),
    timelineFeature(),
  ] as const,
})

export const { MediaProvider, useMediaStore, useMediaApi, useMediaEvents } =
  media

Add UI components

npx shadcn add @limeplay/media @limeplay/playback-control @limeplay/volume-control @limeplay/timeline-control @limeplay/player-layout

Compose the player

components/media-player.tsx

"use client"

import { MediaProvider } from "@/lib/media"
import { Media } from "@/components/limeplay/media"
import { PlaybackControl } from "@/components/limeplay/playback-control"
import * as Volume from "@/components/limeplay/volume-control"
import * as Timeline from "@/components/limeplay/timeline-control"
import * as Layout from "@/components/limeplay/player-layout"
import { PlaybackSourceController } from "@/hooks/limeplay/use-playback-source"

export function MediaPlayer({ src }: { src: string }) {
  return (
    <MediaProvider>
      <PlaybackSourceController source={src} />
      <Layout.PlayerContainer>
        <Media as="video" />
        <Layout.ControlsContainer>
          <Timeline.Root>
            <Timeline.Track>
              <Timeline.Progress />
            </Timeline.Track>
          </Timeline.Root>
          <PlaybackControl />
          <Volume.Root>
            <Volume.Track>
              <Volume.Input />
            </Volume.Track>
          </Volume.Root>
        </Layout.ControlsContainer>
      </Layout.PlayerContainer>
    </MediaProvider>
  )
}

Render with content

Render your player with a source. PlaybackSourceController passes this source through useAsset, so the same pattern works for URLs, asset objects, and playlists.

app/page.tsx

import { MediaPlayer } from "@/components/media-player"

export default function Page() {
  return (
    <MediaPlayer src="https://storage.googleapis.com/shaka-demo-assets/angel-one/dash.mpd" />
  )
}

For blocks, custom loading, playlists, error recovery, and preloading, see Usage.

Next Steps

Concepts — understand the feature system and event architecture
Components — browse all available UI components
Hooks — explore the feature hooks and utilities

On this page