Components / Application

Document

A file and folder element for scheme document libraries. Three layouts cover list spaces (dense rows), thing spaces (card tiles), and wide spaces (tabular metadata). Type icons, size, and modified date are formatted automatically.

Design rationale

File browsers work best when the layout matches the container width. Dense list rows suit narrow sidebars and mobile panels. Card tiles suit grids and pickers where each file is a discrete object. Wide rows with explicit columns suit document managers where users compare size and modified date across many files at once.

Rather than rainbow file-type colours, the component uses the Instant Strata palette: lime-soft icon tiles for primary documents, off-white for secondary types, and a mono type badge via DocumentTypeBadge, which composes Badge. See the Badge docs for every file type label.

Metadata is joined with middle dots, matching existing card and list patterns. Actions stay icon-only with accessible labels, and filenames truncate rather than wrapping, which preserves scanability in long document lists.

Installation

bash

npx shadcn add https://raw.githubusercontent.com/levi-putna/elements/main/registry/document/registry.json

Requires the badge component.

Usage

tsx

import { Document, DocumentList } from "@/components/ui/document"

<DocumentList>
  <Document
    layout="list"
    title="AGM Minutes"
    name="AGM minutes · March 2026.pdf"
    size={248320}
    modifiedAt="2026-03-14"
    folder="Harbour View Towers"
    onDownload={() => {}}
    onShare={() => {}}
  />
</DocumentList>

Examples

List layout

Dense rows for narrow list spaces, sidebars, and stacked file lists.

List space · max 520px

AGM Minutes

AGM minutes · March 2026.pdf · 243 KB · Harbour View Towers · 14 Mar 2026

Budget Forecast

Budget forecast FY26.xlsx · 1.0 MB · Financials · 28 Feb 2026

By-law Register

By-law register.pdf · 500 KB · Compliance · 10 Jan 2026

tsx

import { Document, DocumentList } from "@/components/ui/document"

<DocumentList>
  <Document
    layout="list"
    title="AGM Minutes"
    name="AGM minutes · March 2026.pdf"
    size={248320}
    modifiedAt="2026-03-14"
    folder="Harbour View Towers"
    onDownload={() => {}}
    onShare={() => {}}
  />
</DocumentList>

Thing layout

Card tiles for grids, dashboards, and file pickers where each document is a discrete object.

Thing space · responsive grid

AGM Minutes

AGM minutes · March 2026.pdf · 243 KB · Harbour View Towers

Budget Forecast

Budget forecast FY26.xlsx · 1.0 MB · Financials

By-law Register

By-law register.pdf · 500 KB · Compliance

Insurance Certificate

Insurance certificate 2026.pdf · 872 KB · Insurance

tsx

import { Document, DocumentGrid } from "@/components/ui/document"

<DocumentGrid columns={3}>
  <Document
    layout="thing"
    title="Budget Forecast"
    name="Budget forecast FY26.xlsx"
    size={1048576}
    folder="Financials"
    showChevron
    href="#"
  />
</DocumentGrid>

Wide layout

Full-width rows with type, size, and modified columns for document manager views in wide containers.

Wide space · full container width

Name

Type

Size

Modified

AGM Minutes

AGM minutes · March 2026.pdf · Harbour View Towers

PDF

243 KB

14 Mar 2026

Budget Forecast

Budget forecast FY26.xlsx · Financials

XLSX

1.0 MB

28 Feb 2026

By-law Register

By-law register.pdf · Compliance

PDF

500 KB

10 Jan 2026

Insurance Certificate

Insurance certificate 2026.pdf · Insurance

PDF

872 KB

5 Jan 2026

tsx

import { Document, DocumentList } from "@/components/ui/document"

<DocumentList showWideHeader>
  <Document
    layout="wide"
    title="Insurance Certificate"
    name="Insurance certificate 2026.pdf"
    size={892416}
    modifiedAt="2026-01-05"
    folder="Insurance"
    onDownload={() => {}}
  />
</DocumentList>

File thumbnails

Mini file cards with type-specific placeholder art and a forest/lime extension badge. Sizes scale across list, default, and thing layouts.

DocumentFileThumb · all sizes

DocumentFileThumb · type variants

DocumentTypeBadge

PDFXLSXPPTX

All file type labels and brand colours are listed on the Badge page.

Selected state

Selected row

AGM Minutes

AGM minutes · March 2026.pdf · 243 KB · Harbour View Towers · 14 Mar 2026

Budget Forecast

Budget forecast FY26.xlsx · 1.0 MB · Financials

Props

Document

Prop	Type	Default	Description
title	string	-	Human-readable document title shown as the primary label.
name	string	-	Filename. Shown as secondary metadata when different from the title.
type	DocumentType	-	File type. Inferred from the filename when omitted.
size	number	-	File size in bytes. Formatted automatically in metadata.
modifiedAt	string \| Date	-	Last modified date. Formatted for Australian locale.
folder	string	-	Parent folder or scheme context shown in metadata.
layout	"list" \| "thing" \| "wide"	"list"	list = dense row. thing = card tile. wide = metadata columns for wide spaces.
href	string	-	When set, renders the document as a link.
showChevron	boolean	false	Shows a trailing chevron for navigable rows.
onDownload	() => void	-	When set, renders a download action button.
onShare	() => void	-	When set, renders an open/share action button.
actions	ReactNode	-	Custom trailing actions. Replaces the default download/share buttons.
selected	boolean	false	Highlights the row with a lime-soft background.

DocumentList

Prop	Type	Default	Description
showWideHeader	boolean	false	Renders column headings above wide-layout rows.

DocumentGrid

Prop	Type	Default	Description
columns	2 \| 3 \| 4	3	Responsive column count for thing-layout cards.