Skip to the content

Controls and surfaces

media-row-list

The pictures or clips a person has added, as rows they can put in order, describe and choose a cover from: each row shows its state in words (an upload's, or one the project names), its progress or its error with pause, resume and retry, a field for its text alternative that can be required, a "cover" choice, a remove button, and room for a status line and controls of the project's own.

When to use it

After a dropzone, when the order of the files matters and each needs a description: the photos of a listing, the slides of a story, the pages of a document. It is ready-made from sortable-list (drag by the handle, lift and move with the keyboard, or the move buttons; every move is read out) and the upload rows of dropzone, and contains no upload engine: the project uploads and passes each row its state. For files whose order does not matter use the dropzone's own UploadList; to reorder things that are not files use sortable-list.

Add it

npx shadcn@latest add @rivier-ui/media-row-list

The registry is named once in components.json: see Installation.

Example

Import it from @/components/ui/media-row-list.

const [rows, setRows] = useState<MediaRow[]>([
  { id: "a", name: "kitchen.jpg", size: 1_200_000, state: "done", alt: "The kitchen, from the door" },
  { id: "b", name: "garden.jpg", size: 2_400_000, state: "uploading", progress: 40 },
  { id: "c", name: "stairs.jpg", state: "failed", error: "The connection dropped." },
]);
const [cover, setCover] = useState<string | null>("a");
<MediaRowList
  aria-label="Pictures, in order"
  items={rows}
  onItemsChange={setRows}
  cover={cover}
  onCoverChange={setCover}
  onAltChange={(id, alt) => setRows((all) => all.map((row) => (row.id === id ? { ...row, alt } : row)))}
  onRemove={(id) => setRows((all) => all.filter((row) => row.id !== id))}
  onRetry={(id) => upload(id)}
/>

// A state of the project's own, a status line, a control of its own, no cover choice, and a description that is required
const row: MediaRow = {
  id: "d", name: "walk.mp4", state: "checking", stateLabel: "Being checked", stateTone: "warning",
  status: "Usually takes a minute.", controls: <Button size="sm" variant="ghost">Trim</Button>,
  hideCover: true, altRequired: true, altError: "Say what the clip shows.",
};
<MediaRowList aria-label="Clips" items={[row]} variant="lines" onAltChange={describe} onPause={pause} onResume={resume} onDropped={({ values }) => save(values)} />

What it needs

A client component: it uses state, effects or browser behaviour. Packages: lucide-react.

It imports

Source

The whole file. Once copied it is yours: the registry item holds the same text.

src/components/ui/media-row-list.tsx
"use client";
/**
 * @name media-row-list
 * @category ui
 * @description The pictures or clips a person has added, as rows they can put in order, describe and choose a cover from: each row shows its state in words (an upload's, or one the project names), its progress or its error with pause, resume and retry, a field for its text alternative that can be required, a "cover" choice, a remove button, and room for a status line and controls of the project's own.
 * @when After a dropzone, when the order of the files matters and each needs a description: the photos of a listing, the slides of a story, the pages of a document. It is ready-made from sortable-list (drag by the handle, lift and move with the keyboard, or the move buttons; every move is read out) and the upload rows of dropzone, and contains no upload engine: the project uploads and passes each row its state. For files whose order does not matter use the dropzone's own UploadList; to reorder things that are not files use sortable-list.
 * @example
 * const [rows, setRows] = useState<MediaRow[]>([
 *   { id: "a", name: "kitchen.jpg", size: 1_200_000, state: "done", alt: "The kitchen, from the door" },
 *   { id: "b", name: "garden.jpg", size: 2_400_000, state: "uploading", progress: 40 },
 *   { id: "c", name: "stairs.jpg", state: "failed", error: "The connection dropped." },
 * ]);
 * const [cover, setCover] = useState<string | null>("a");
 * <MediaRowList
 *   aria-label="Pictures, in order"
 *   items={rows}
 *   onItemsChange={setRows}
 *   cover={cover}
 *   onCoverChange={setCover}
 *   onAltChange={(id, alt) => setRows((all) => all.map((row) => (row.id === id ? { ...row, alt } : row)))}
 *   onRemove={(id) => setRows((all) => all.filter((row) => row.id !== id))}
 *   onRetry={(id) => upload(id)}
 * />
 *
 * // A state of the project's own, a status line, a control of its own, no cover choice, and a description that is required
 * const row: MediaRow = {
 *   id: "d", name: "walk.mp4", state: "checking", stateLabel: "Being checked", stateTone: "warning",
 *   status: "Usually takes a minute.", controls: <Button size="sm" variant="ghost">Trim</Button>,
 *   hideCover: true, altRequired: true, altError: "Say what the clip shows.",
 * };
 * <MediaRowList aria-label="Clips" items={[row]} variant="lines" onAltChange={describe} onPause={pause} onResume={resume} onDropped={({ values }) => save(values)} />
 */
import { CircleAlert } from "lucide-react";
import { useEffect, useId, useRef, type ComponentProps, type ReactNode } from "react";
import { UploadActions, UploadItem, UploadPause, UploadProgress, UploadRemove, UploadResume, UploadRetry, type UploadState, type UploadTone } from "@/components/ui/dropzone";
import { Input } from "@/components/ui/input";
import { SortableHandle, SortableItem, SortableList, SortableMoveButtons, type SortableDrop, type SortableMessages } from "@/components/ui/sortable-list";
import { announce } from "@/lib/announce";
import { cn } from "@/lib/cn";
import { useControllableState } from "@/lib/use-controllable-state";

/** One file, as plain data. */
export type MediaRow = {
  /** Unique among the rows. */
  id: string;
  /** The file's name: shown, and used in the names of the row's controls. */
  name: string;
  /** Its size in bytes. */
  size?: number;
  /** Where its upload is (a file that is already stored is "done"), or a state of the project's own ("checking", "published"): give that one a `stateLabel`. */
  state: UploadState | (string & {});
  /** The word for this row's state: it replaces the list's `stateLabels`. Needed for a state of the project's own. */
  stateLabel?: string;
  /** How the state reads: "neutral", "success", "warning" or "destructive", each with its own mark. Default: by the state. */
  stateTone?: UploadTone;
  /** How much has been sent, 0 to 100. The bar shows while the row is not "done". */
  progress?: number;
  /** Why it failed, in the project's words, shown after the state's word on a failed row (or one whose tone is "destructive"). */
  error?: ReactNode;
  /** A line of the row's own under its name and state: what is happening to it, or what it is waiting for. */
  status?: ReactNode;
  /** Controls of the project's own for this row (buttons, a menu), beside the cover choice. Name each after the file. */
  controls?: ReactNode;
  /** Leave the cover choice out of this row: a clip that cannot be a cover, a file still being checked. */
  hideCover?: boolean;
  /** The description must be given: the field says so in words and to a screen reader. */
  altRequired?: boolean;
  /** The description is not acceptable. Default: true when there is an `altError`. */
  altInvalid?: boolean;
  /** What is wrong with the description, in words the person can act on: shown under the field, tied to it, and read out when it appears. */
  altError?: string;
  /** A small picture of it (an `<img alt="">`: the name is beside it). */
  thumbnail?: ReactNode;
  /** Its text alternative: what the picture shows, for people who cannot see it. */
  alt?: string;
};

/** The words shown and read out. Translate them with the interface. */
export type MediaRowLabels = {
  /** The visible label of the text-alternative field. */
  alt: string;
  /** The field's name for a screen reader, which must tell the rows apart. */
  altFor: (name: string) => string;
  /** The hint inside an empty field. */
  altPlaceholder: string;
  /** The word after the field's label when a description must be given. */
  required: string;
  /** Read out when a description's error appears. */
  altErrorFor: (name: string, error: string) => string;
  /** The visible label of the cover choice. */
  cover: string;
  /** The choice's name for a screen reader. */
  coverFor: (name: string) => string;
  /** The words on the row that is the cover. */
  isCover: string;
  /** Read out when the cover changes. */
  coverChanged: (name: string) => string;
  retry: string;
  pause: string;
  resume: string;
  remove: string;
  /** Read out when a row is removed. */
  removed: (name: string) => string;
};

export const MEDIA_ROW_LABELS: MediaRowLabels = {
  alt: "Description",
  altFor: (name) => `Description of ${name}`,
  altPlaceholder: "What the picture shows",
  required: "required",
  altErrorFor: (name, error) => `${name}: ${error}`,
  cover: "Cover",
  coverFor: (name) => `Cover: ${name}`,
  isCover: "Cover picture",
  coverChanged: (name) => `${name} is now the cover.`,
  retry: "Try again",
  pause: "Pause",
  resume: "Resume",
  remove: "Remove",
  removed: (name) => `${name} removed.`,
};

export type MediaRowListProps = Omit<ComponentProps<"div">, "children" | "onChange" | "onPause"> & {
  /** The rows, in order. */
  items: readonly MediaRow[];
  /** The rows in their new order, after a move. */
  onItemsChange?: (items: MediaRow[]) => void;
  /** The ids in their new order, after a move (the same moment as `onItemsChange`). */
  onReorder?: (ids: string[]) => void;
  /** Called once when a move ends (a dragged row is let go, a lifted row is dropped, a move button is pressed), with the row, where it was, where it is and the new order: the place to save. */
  onDropped?: (drop: SortableDrop) => void;
  /** Take the row out. Left out, rows have no remove button. */
  onRemove?: (id: string) => void;
  /** Try a failed row again. Left out, failed rows have no retry button. */
  onRetry?: (id: string) => void;
  /** Pause a row that is "uploading". Left out, there is no pause button. */
  onPause?: (id: string) => void;
  /** Carry on a row that is "paused". Left out, there is no resume button. */
  onResume?: (id: string) => void;
  /** The text alternative was edited. Left out, rows have no description field. */
  onAltChange?: (id: string, alt: string) => void;
  /** The id of the cover row, or null for none: controlled. */
  cover?: string | null;
  /** The cover when uncontrolled. Default: none. */
  defaultCover?: string | null;
  /** Called with the new cover. When the cover row is removed, it is called with the first row left (or null). */
  onCoverChange?: (id: string | null) => void;
  /** Leave out the cover choice in every row. One row leaves it out with its own `hideCover`. */
  hideCover?: boolean;
  /** Every row's description must be given. One row says so with its own `altRequired`. */
  altRequired?: boolean;
  /** "cards" (default): each row a bordered surface. "lines": rows with a hairline between them and no box, for a list inside a card or a panel. */
  variant?: "cards" | "lines";
  /** Stops reordering and every control. */
  disabled?: boolean;
  /** The words, where the English defaults are not wanted. */
  labels?: Partial<MediaRowLabels>;
  /** The words of the reordering (lifted, moved, dropped, the handle and the move buttons). */
  sortableMessages?: Partial<SortableMessages>;
  /** The word for each upload state. */
  stateLabels?: Partial<Record<UploadState, string>>;
  /** For sizes and percentages. Default: the browser's. */
  locale?: string;
  /** Shown instead of the list when there are no rows. */
  empty?: ReactNode;
};

type AltFieldProps = {
  id: string;
  row: MediaRow;
  words: MediaRowLabels;
  required: boolean;
  disabled: boolean;
  onChange: (alt: string) => void;
};

/** The description field of one row: labelled, required or not, and with its error tied to it and read out when it appears. */
function AltField({ id, row, words, required, disabled, onChange }: AltFieldProps) {
  const error = row.altError?.trim() || undefined;
  const invalid = row.altInvalid ?? error !== undefined;
  const errorId = `${id}-error`;
  const { name } = row;
  const say = words.altErrorFor;
  // An error that arrives is said once. One that is already there when the row is first shown is not: a page that opens with ten of them would read ten.
  const said = useRef(error);
  useEffect(() => {
    if (said.current === error) return;
    said.current = error;
    if (error) announce(say(name, error));
  }, [error, name, say]);

  return (
    <div className="flex min-w-40 flex-1 flex-col gap-1">
      <label htmlFor={id} className="text-xs font-medium text-muted-foreground">
        {words.alt}
        {required ? <span data-slot="media-row-alt-required"> ({words.required})</span> : null}
      </label>
      <Input
        id={id}
        data-slot="media-row-alt"
        size="sm"
        dir="auto"
        autoComplete="off"
        aria-label={words.altFor(name)}
        aria-invalid={invalid || undefined}
        aria-describedby={error ? errorId : undefined}
        required={required}
        placeholder={words.altPlaceholder}
        value={row.alt ?? ""}
        disabled={disabled}
        onChange={(event) => onChange(event.target.value)}
        className="pointer-coarse:h-control"
      />
      {error ? (
        <p id={errorId} data-slot="media-row-alt-error" className="flex items-start gap-1 text-xs text-destructive">
          <CircleAlert aria-hidden="true" strokeWidth={1.5} className="mt-0.5 size-3.5 shrink-0" />
          <span>{error}</span>
        </p>
      ) : null}
    </div>
  );
}

/**
 * An ordered list, so a row is read as "2 of 5". Name it with `aria-label` or `aria-labelledby`. The
 * cover choices are radio buttons that share one name: exactly one row can be the cover, Tab stops on the
 * chosen one and the arrow keys move the choice between rows, as in any radio group. A failed row cannot
 * be the cover. After a row is removed, focus goes to the row that took its place (or the one before, or
 * the list itself when it was the last), and the removal is read out. A row is a surface, with the
 * surface's corners at every roundness (never a pill), or a line with a hairline under it.
 */
export function MediaRowList({
  className,
  items,
  onItemsChange,
  onReorder,
  onDropped,
  onRemove,
  onRetry,
  onPause,
  onResume,
  onAltChange,
  cover,
  defaultCover = null,
  onCoverChange,
  hideCover = false,
  altRequired = false,
  variant = "cards",
  disabled = false,
  labels,
  sortableMessages,
  stateLabels,
  locale,
  empty,
  "aria-label": ariaLabel,
  "aria-labelledby": ariaLabelledBy,
  ...props
}: MediaRowListProps) {
  const words = { ...MEDIA_ROW_LABELS, ...labels };
  const group = useId();
  const root = useRef<HTMLDivElement>(null);
  const [chosen, setChosen] = useControllableState<string | null>({ value: cover, defaultValue: defaultCover, onChange: onCoverChange });
  const ids = items.map((item) => item.id);

  const reorder = (next: string[]): void => {
    onReorder?.(next);
    const byId = new Map(items.map((item) => [item.id, item]));
    onItemsChange?.(next.flatMap((id) => byId.get(id) ?? []));
  };

  const remove = (item: MediaRow): void => {
    const at = ids.indexOf(item.id);
    const neighbour = ids[at + 1] ?? ids[at - 1];
    if (chosen === item.id) setChosen(items.find((other) => other.id !== item.id && other.state !== "failed" && !other.hideCover)?.id ?? null);
    onRemove?.(item.id);
    announce(words.removed(item.name));
    // Once the row is gone, the keyboard's place is the row that took its place.
    requestAnimationFrame(() => {
      const box = root.current;
      if (!box) return;
      const row = neighbour === undefined ? null : [...box.querySelectorAll<HTMLElement>("[data-slot=media-row]")].find((node) => node.dataset["row"] === neighbour);
      (row?.querySelector<HTMLElement>("[data-slot=sortable-handle]:not(:disabled), [data-slot=upload-remove]") ?? box).focus();
    });
  };

  return (
    <div ref={root} data-slot="media-row-list" data-variant={variant} tabIndex={-1} className={cn("w-full min-w-0", className)} {...props}>
      {items.length === 0 && empty ? (
        <div data-slot="media-row-empty" className="text-sm text-muted-foreground">
          {empty}
        </div>
      ) : (
        <SortableList
          values={ids}
          onValuesChange={reorder}
          disabled={disabled}
          aria-label={ariaLabel}
          aria-labelledby={ariaLabelledBy}
          className={variant === "lines" ? "gap-0" : undefined}
          {...(onDropped ? { onDropped } : {})}
          {...(sortableMessages ? { messages: sortableMessages } : {})}
        >
          {items.map((item) => {
            const isCover = chosen === item.id;
            const failed = item.state === "failed";
            const showError = item.error !== undefined && (failed || item.stateTone === "destructive");
            const withCover = !hideCover && !item.hideCover;
            const altId = `${group}-alt-${item.id}`;
            return (
              <SortableItem
                key={item.id}
                value={item.id}
                label={item.name}
                data-slot="media-row"
                data-row={item.id}
                data-cover={isCover ? "" : undefined}
                // A row holds several lines: it takes the surface's corners, which stay corners when controls become pills.
                className={cn("items-start gap-1 p-2", variant === "lines" ? "rounded-none border-0 border-b bg-transparent px-0 last:border-b-0" : "rounded-surface")}
              >
                <SortableHandle className="mt-1" />
                <UploadItem
                  as="div"
                  name={item.name}
                  state={item.state}
                  className="min-w-0 flex-1 rounded-none border-0 bg-transparent p-1"
                  {...(item.stateLabel !== undefined ? { stateLabel: item.stateLabel } : {})}
                  {...(item.stateTone !== undefined ? { stateTone: item.stateTone } : {})}
                  {...(item.size !== undefined ? { size: item.size } : {})}
                  {...(item.thumbnail ? { thumbnail: item.thumbnail } : {})}
                  {...(stateLabels ? { stateLabels } : {})}
                  {...(locale ? { locale } : {})}
                  detail={
                    showError || isCover ? (
                      <>
                        {showError ? item.error : null}
                        {isCover ? (
                          <span data-slot="media-row-cover-mark" className="rounded-control border border-border-strong px-1.5 font-medium text-foreground">
                            {words.isCover}
                          </span>
                        ) : null}
                      </>
                    ) : undefined
                  }
                >
                  {item.state !== "done" && item.progress !== undefined ? <UploadProgress value={item.progress} /> : null}
                  <UploadActions className="self-start">
                    {item.state === "uploading" && onPause ? <UploadPause label={words.pause} disabled={disabled} onClick={() => onPause(item.id)} /> : null}
                    {item.state === "paused" && onResume ? <UploadResume label={words.resume} disabled={disabled} onClick={() => onResume(item.id)} /> : null}
                    {failed && onRetry ? <UploadRetry label={words.retry} disabled={disabled} onClick={() => onRetry(item.id)} /> : null}
                    {onRemove ? <UploadRemove label={words.remove} disabled={disabled} onClick={() => remove(item)} /> : null}
                  </UploadActions>
                  {item.status ? (
                    <p data-slot="media-row-status" className="col-span-full min-w-0 text-xs text-muted-foreground">
                      {item.status}
                    </p>
                  ) : null}
                  <div data-slot="media-row-details" className="col-span-full flex min-w-0 flex-wrap items-end gap-x-3 gap-y-2 pt-1">
                    {onAltChange ? <AltField id={altId} row={item} words={words} required={altRequired || item.altRequired === true} disabled={disabled} onChange={(alt) => onAltChange(item.id, alt)} /> : null}
                    <div className="ms-auto flex shrink-0 flex-wrap items-center justify-end gap-1">
                      {item.controls ? (
                        <div data-slot="media-row-controls" className="flex shrink-0 items-center gap-1">
                          {item.controls}
                        </div>
                      ) : null}
                      {withCover ? (
                        <label
                          data-slot="media-row-cover"
                          className={cn(
                            "inline-flex h-control-sm items-center gap-2 rounded-control px-2 text-sm text-foreground hover:bg-accent has-disabled:pointer-events-none has-disabled:opacity-50 pointer-coarse:h-control",
                            isCover && "font-medium",
                          )}
                        >
                          <input
                            type="radio"
                            name={`${group}-cover`}
                            value={item.id}
                            checked={isCover}
                            disabled={disabled || failed}
                            aria-label={words.coverFor(item.name)}
                            onChange={() => {
                              setChosen(item.id);
                              announce(words.coverChanged(item.name));
                            }}
                            className="size-4 shrink-0 accent-primary"
                          />
                          {words.cover}
                        </label>
                      ) : null}
                      <SortableMoveButtons className="ms-0" />
                    </div>
                  </div>
                </UploadItem>
              </SortableItem>
            );
          })}
        </SortableList>
      )}
    </div>
  );
}