Uploader

uploader provides CommonUploaderButton: a client-side dialog workflow to download a template, choose a format, pick a spreadsheet, validate it, and submit parsed records or the raw file to your API.

format → template → file → parse (records mode) → validate → submit → history/redirect

The component owns dialog state, file selection, parsing feedback, and upload feedback. Your application owns persistence, authorization, server-side validation, and import-job status.

When to use itCopy Anchor Link

• Bulk create or update flows driven by a spreadsheet template
• Imports where users must fix row-level errors before submit
• Optional file transport when the backend prefers the raw XLSX/CSV instead of parsed rows

InstallationCopy Anchor Link

pnpm dlx shadcn@latest add https://feature-kits.vercel.app/r/uploader.json

pnpm add uploader form ui

// apps/your-app/package.json
"dependencies": {
    "uploader": "workspace:*"
    "form": "workspace:*"
    "ui": "workspace:*"
}

// next.config.ts
transpilePackages: ["uploader", "form", "ui"]

import { CommonUploaderButton, type UploaderConfig } from "@/lib/feature-kit/uploader"

UsageCopy Anchor Link

Column definitionCopy Anchor Link

Each UploaderColumn maps a spreadsheet header to a record key:

Modes and transportCopy Anchor Link

• defaultMode — selects the create or update validation mode. The current button does not render a mode switcher; render separate configured buttons if users need both modes.
• transport: "records" (default) — parse the file in the browser, validate required columns and custom rules, then call onUpload.
• transport: "file" — skip record parsing and call onUploadFile with the original File and selected formatCode. This is useful when the server owns parsing or large-file processing.

In records mode, upload is disabled when parsing is pending, no records were found, or any parse/validation issue exists. In file mode, upload requires an accepted file, a selected format, and onUploadFile.

Cross-row validationCopy Anchor Link

validateParsedRecords: (records, mode) => {
  if (mode === "create" && records.length > 500) {
    return [{ row: 1, message: "Max 500 rows per import" }]
  }
  return []
}

Flat validation reports spreadsheet rows using one-based spreadsheet numbering (the first data row is normally row 2). Cross-row validation can return a row-level error without a column. The UI displays up to five issues inline and reports the remainder as truncated.

Templates, formats, and historyCopy Anchor Link

downloadUploaderTemplate generates an .xlsx workbook from columns, using each header and optional sample. Pass onDownloadTemplate when templates are generated by the server or depend on the selected format. loadFormatCodes or loadFormatOptions can provide dynamic formats; loadFormatOptions supplies user-facing labels.

After a successful upload, the default behavior navigates to config.historyHref (default /file-processing/import-history). Set redirectOnSuccess={false} for an embedded flow. When buildSuccessRedirectHref is present and a filename is available, its returned URL replaces historyHref, which lets the host filter import history by filename and format.

API referenceCopy Anchor Link

UploaderConfigCopy Anchor Link

CommonUploaderButtonCopy Anchor Link

GotchasCopy Anchor Link

Live preview with sample data in the docs. Uploader preview — full column config in apps/web/src/components/examples/uploader/demo-uploader-columns.ts.

AccessibilityCopy Anchor Link

The dialog exposes labeled format and file controls, supports drag-and-drop plus the native file picker, and announces parse/upload failures in an alert. Keep triggerLabel, title, and description specific to the entity being imported. Test keyboard access to the dropzone and template/download controls.