FilePicker

A dashed box you drop files on, or press to open the file dialog.

import { FilePicker } from 'neba';

<FilePicker
  multiple
  label="Attachments"
  accept="image/*,.pdf"
  maxSize={5_000_000}
  maxFiles={4}
  onFilesChange={setFiles}
  onReject={setRejected}
/>;

Props

Prop	Type	Default	Description
variantshared	'solid' | 'outline' | 'text'	'outline'	Weight of the surface. All three share the dashed edge — the one place the library draws a line that is not solid, because a dashed rectangle is the established sign for a drop target
sizeshared	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'	The box's padding and type scale. A dropzone is sized by the gesture it has to catch, not by what is written in it
colorshared	'primary' | 'secondary' | 'success' | 'warning' | 'danger' | 'info'	'primary'	Semantic colour role. Arbitrary colour values are not accepted
densityshared	'default' | 'compact'	'default'	Padding only — never the height, never the type scale
elevationshared	0 | 1 | 2 | 3	0	Drop shadow depth. 0 means no shadow at all
accept	string	—	Which files the browser's own picker offers — 'image/*,.pdf'. Dropped files are checked against it too, which the attribute alone does not do
multiple	boolean	false	Whether more than one file may be chosen
maxSize	number	—	The largest a single file may be, in bytes
maxFiles	number	—	How many files may be held at once — counted against what is already chosen, not against one drop
value	readonly File[]	—	The chosen files, for a controlled picker
defaultValue	readonly File[]	—	The initially chosen files
onFilesChange	(files: File[]) => void	—	Called when the list of files changes
onReject	(rejections: FileRejection[]) => void	—	Called with everything turned away, and why. Without it a rejected file disappears silently, which is the worst thing a dropzone does
title	ReactNode	—	The line inside the box
hint	ReactNode	—	The line under it — what is accepted, how big, how many
icon	ReactNode	—	The glyph above the title. Pass null for a box with no picture in it
showList	boolean	true	Lists the chosen files under the box, each with a way to remove it
removeLabel	(name: string) => string	—	Accessible name of a file's remove button
label	ReactNode	—	The label, wired to the control by Base UI's Field
description	ReactNode	—	Helper text
error	ReactNode	—	Error message. Its presence turns the control invalid and re-points the colour family at danger
invalid	boolean	!!error	Forces the invalid state without a message, for when a form library owns validity
readOnly	boolean	false	Shown but not changeable. Keeps its colour and edge, drains the saturation
disabled	boolean	false	Unavailable. Drops the colour family for neutral grey
fullWidth	boolean	true	Stretches to the width of the container
required	boolean	false	Whether a file must be chosen before the form is submitted
name	string	—	Identifies the field when a form is submitted

Examples

Variants

All three share the dashed edge. It is the one place in the library that draws a line which is not solid, and it is not decoration — a dashed rectangle is the established sign for "this area accepts a drop", and a dropzone that looks like a card is a card nobody tries to drop on.

import { FilePicker } from 'neba';

export default function FilePickerVariants() {
  return (
    <div className="grid w-full grid-cols-1 gap-4 lg:grid-cols-3">
      {(['solid', 'outline', 'text'] as const).map((variant) => (
        <FilePicker key={variant} variant={variant} size="sm" title={variant} hint="Any file" />
      ))}
    </div>
  );
}

What it turns away

import { useState } from 'react';
import { Alert, FilePicker, type FileRejection } from 'neba';

const WHY: Record<FileRejection['reason'], string> = {
  type: 'is not an image',
  size: 'is over 100 kB',
  count: 'would be the third file'
};

/**
 * A rejected file that vanishes without a word is the worst thing a dropzone
 * does, which is why `onReject` exists at all: the component turns files away,
 * and only the application knows how to say so.
 */
export default function FilePickerRejection() {
  const [files, setFiles] = useState<File[]>([]);
  const [rejected, setRejected] = useState<FileRejection[]>([]);

  return (
    <div className="flex w-full flex-col gap-3">
      <FilePicker
        multiple
        accept="image/*"
        maxSize={100_000}
        maxFiles={2}
        title="Images only, under 100 kB, two at a time"
        hint="Try dropping something else"
        value={files}
        onFilesChange={(next) => {
          setFiles(next);
          setRejected([]);
        }}
        onReject={setRejected}
      />

      {rejected.length > 0 ? (
        <Alert color="warning" title="Some files were turned away" onClose={() => setRejected([])}>
          {rejected.map(({ file, reason }) => `${file.name} ${WHY[reason]}`).join(' · ')}
        </Alert>
      ) : null}
    </div>
  );
}

States

import { FilePicker } from 'neba';

const SAMPLE = [new File(['x'.repeat(24_000)], 'design-spec.pdf', { type: 'application/pdf' })];

export default function FilePickerStates() {
  return (
    <div className="grid w-full grid-cols-1 gap-4 lg:grid-cols-2">
      <FilePicker
        size="sm"
        label="Required"
        required
        error="Pick a file before saving."
        title="Nothing here yet"
      />

      <FilePicker size="sm" label="Read-only" readOnly defaultValue={SAMPLE} title="Locked" />

      <FilePicker size="sm" label="Disabled" disabled title="Unavailable" />

      <FilePicker
        size="sm"
        label="No picture, no list"
        icon={null}
        showList={false}
        defaultValue={SAMPLE}
        title="Just the sentence"
        hint="icon={null} · showList={false}"
      />
    </div>
  );
}

The browser does not apply accept to a dropped file

The accept attribute governs the browser's own file dialog and nothing else. A file that arrived by drag has never been checked against that string. A dropzone that only sets the attribute accepts anything the moment a file comes in by drop.

This component runs the check itself, against the same string, in the three forms the attribute takes: .ext, type/subtype, and type/*.

A drag state that does not flicker

dragenter and dragleave fire for every child of the zone the pointer crosses. A dropzone that toggles a boolean therefore flickers the entire time a file is being dragged over its own contents. Counting the events is the fix, and the only thing that survives a zone with content in it.

maxFiles is not "you may drop this many"

It is "you may end up with this many". It is checked against what is already held, so dropping three files on a maxFiles={3} picker that holds two accepts exactly one of them.

Why there is no Base UI primitive

A dropzone is a <div> listening for four drag events and an <input type="file"> it clicks for you. There is no popup to position, no focus to trap and no roving anything. The fallback the design language allows — plain React and DOM — is the right one here.

What is left is the part hand-rolled dropzones usually get wrong, which is the three sections above.

Accessibility

The shell is a <div> and the pressable area inside it is a real <button>. The file list sits outside that button, because the remove buttons cannot be nested inside the browse button — the same shape Chip and ListItem use.

The real <input type="file"> is moved off-screen rather than hidden. display: none and visibility: hidden both make an input unfocusable in some browsers, and this one still has to be reachable to a form and to a required validation message.

Pass onReject. Without it a rejected file disappears without a word.