Media Picker

Pro

In-app photo and video grid for picking one item or several. Each pick flies into a tray with a numbered badge, and reaching the limit gives a gentle warning.

Preview

Installation

npx @lumioui/cli add pro/media-picker

Usage

import { MediaPicker } from "@/components/ui/media-picker/media-picker";
<MediaPicker />

Examples

Chat attachment sheet

The attachment sheet in a conversation.

Listing photos with cover

Adding photos to a for-sale listing.

Create post, numbered picks

Composing a multi-photo post.

Profile photo with crop circle

Choosing a profile photo.

API reference

Prop Type Default
items* MediaPickerItem[] —
selected string[]

Controlled selection, in pick order.

 —
defaultSelected string[]

Uncontrolled initial selection.

 []
onSelectedChange (ids: string[]) => void —
mode "multiple" | "single"

"multiple" numbers picks; "single" swaps one pick with a check. Default "multiple".

 "multiple"
max number

Most items in a multiple pick. Default 10.

 10
columns number

Grid columns. Default 3.

 3
gap number

Gap between tiles in points. Default 2.

 2
onCameraPress () => void

Show a camera tile first; fires onCameraPress.

 —
tray boolean

Selected tray along the bottom. Default true in multiple mode.

 —
cover boolean

First pick is the cover; tray thumbs get a promote-to-cover star.

 false
onMaxReached () => void

Fires when a pick is refused because max is reached.

 —
trayAction React.ReactNode

Right side of the tray (Next / Send button).

 —
trayLabel (count: number, max: number) => string

Tray label. Default "{n} selected".

 —
trayThumbSize number

Tray thumbnail edge in points. Default 56.

 56
gathered boolean

Commit: the tray gathers into a fanned stack on the cover pick.

 false
onGathered (ids: string[]) => void

Called once the gathered stack has been held (~650ms after it lands).

 —
gatheredLabel (count: number) => string

Badge on the gathered stack. Default "{n} photos" / "{n} items".

 —
header React.ReactNode

Rendered above the grid, inside the scroll view (album switcher, crop preview).

 —
className string —
contentClassName string

Classes for the scroll content (padding).

 —