File Card - HapplyUI

A compound card component for displaying files with thumbnails, upload progress, download actions, error states, and remove actions. Supports document, image, video, and audio file types. Includes a high-level Item preset for quick rendering from file state.

Installation

bunx @happlyui/cli@latest add file-card

Dependencies

npm packages

@remixicon/react

Registry dependencies

These are automatically installed when you add this component.

tv
happly-ui-utils
button
file-format-icon

Usage

import * as FileCard from "@/components/ui/file-card"

<FileCard.Item
  file={{ id: '1', name: 'file.pdf', size: 2621440, type: 'application/pdf', progress: 100, status: 'completed' }}
  onDownload={() => {}}
/>

Examples

Upload States

Uploading and failed states with progress bar, spinner, retry link, and action buttons.

DataAnalysis.pdf

Uploading...

DataAnalysis.pdf

Failed

<FileCard.Root>
  <FileCard.Thumbnail>
    <FileFormatIcon.Root format="PDF" color="red" size="medium" />
  </FileCard.Thumbnail>
  <FileCard.Content>
    <FileCard.UploadBody>
      <FileCard.InfoGroup>
        <FileCard.Name>DataAnalysis.pdf</FileCard.Name>
        <FileCard.Status status="uploading">Uploading...</FileCard.Status>
      </FileCard.InfoGroup>
      <FileCard.Progress value={10} />
    </FileCard.UploadBody>
    <FileCard.Actions>
      <FileCard.CloseButton />
    </FileCard.Actions>
  </FileCard.Content>
</FileCard.Root>

Completed Media Types

Completed cards for document, image, video, and audio file types with appropriate thumbnails.

DataAnalysis.pdf

2.5 MB

Uploaded on: June 5, 2023

Team_Photo_2025.jpg

2.5 MB

Use a horizontal image (16:9). Best size: 1200 × 675 px.

Founder_Intro_Video.mp4

2.5 MB

Uploaded on: June 5, 2023

Podcast_Clip_Startup_Journey.mp3

2.5 MB

Uploaded on: June 5, 2023

<FileCard.Root>
  <FileCard.Thumbnail>
    <FileFormatIcon.Root format="PDF" color="red" size="medium" />
  </FileCard.Thumbnail>
  <FileCard.Content>
    <FileCard.Body>
      <FileCard.Name>DataAnalysis.pdf</FileCard.Name>
      <FileCard.Meta>2.5 MB</FileCard.Meta>
      <FileCard.Hint>Uploaded on: June 5, 2023</FileCard.Hint>
    </FileCard.Body>
    <FileCard.Actions>
      <FileCard.RemoveButton />
    </FileCard.Actions>
  </FileCard.Content>
</FileCard.Root>

Download

Completed file cards with a download icon button action.

DataAnalysis.pdf

2.5 MB

Uploaded on: June 5, 2023

Team_Photo_2025.jpg

2.5 MB

<FileCard.Root>
  <FileCard.Thumbnail>
    <FileFormatIcon.Root format="PDF" color="red" size="medium" />
  </FileCard.Thumbnail>
  <FileCard.Content>
    <FileCard.Body>
      <FileCard.Name>DataAnalysis.pdf</FileCard.Name>
      <FileCard.Meta>2.5 MB</FileCard.Meta>
    </FileCard.Body>
    <FileCard.Actions>
      <FileCard.DownloadButton />
    </FileCard.Actions>
  </FileCard.Content>
</FileCard.Root>

Compact

Compact variant showing uploading, completed, and failed states with inline layout.

my-cv.pdf

0 KB of 120 KB

∙

Uploading...

my-cv.pdf

0 KB of 120 KB

∙

Completed

my-cv.pdf

0 KB of 120 KB

∙

Failed

<FileCard.CompactRoot>
  <FileCard.CompactContent>
    <FileFormatIcon.Root format="PDF" color="red" size="medium" />
    <FileCard.CompactBody>
      <FileCard.Name>my-cv.pdf</FileCard.Name>
      <FileCard.CompactDescription>
        <FileCard.Meta>0 KB of 120 KB</FileCard.Meta>
        <FileCard.Dot />
        <FileCard.CompactStatus status="uploading">Uploading...</FileCard.CompactStatus>
      </FileCard.CompactDescription>
    </FileCard.CompactBody>
    <FileCard.CloseButton />
  </FileCard.CompactContent>
  <FileCard.Progress value={10} />
</FileCard.CompactRoot>

Item Preset

High-level Item preset rendering uploading, failed, completed document, and completed image states automatically.

DataAnalysis.pdf

Uploading...

DataAnalysis.pdf

Failed

DataAnalysis.pdf

2.5 MB

Team_Photo_2025.jpg

2.5 MB

Image uploaded successfully

<FileCard.Item
  file={{ id: '1', name: 'DataAnalysis.pdf', size: 2621440, type: 'application/pdf', progress: 35, status: 'uploading' }}
  onClose={() => {}}
/>

Item Preset: Download

Item preset with download action for completed files.

DataAnalysis.pdf

2.5 MB

Team_Photo_2025.jpg

2.5 MB

Image uploaded successfully

<FileCard.Item
  file={{ id: '8', name: 'DataAnalysis.pdf', size: 2621440, type: 'application/pdf', progress: 100, status: 'completed' }}
  onDownload={() => {}}
/>

Item Preset: Compact

Item preset in compact variant showing uploading, completed, and failed states.

my-cv.pdf

12.0 KB of 120.0 KB

∙

Uploading...

my-cv.pdf

120.0 KB

∙

Completed

my-cv.pdf

120.0 KB

∙

Failed

<FileCard.Item
  variant="compact"
  file={{ id: '5', name: 'my-cv.pdf', size: 122880, type: 'application/pdf', progress: 10, status: 'uploading' }}
  onClose={() => {}}
/>

API Reference

FileCard.Item

A high-level preset that renders the correct card layout based on file status and variant. Reduces boilerplate by composing the compound sub-components internally.

Prop	Type	Default	Description
`file`	`{ id: string; name: string; size: number; type: string; progress: number; status: 'pending' \| 'uploading' \| 'completed' \| 'failed'; url?: string; preview?: string; error?: string }`	-	The file state object. Compatible with useFileUpload hook's UploadFile type.
`variant`	`'default' \| 'compact'`	`'default'`	Card layout variant.
`onRemove`	`() => void`	-	Called when the remove/delete button is clicked.
`onRetry`	`() => void`	-	Called when the retry link is clicked (failed state only).
`onClose`	`() => void`	-	Called when the close button is clicked (uploading state only).
`onDownload`	`() => void`	-	Called when the download button is clicked (completed state only).

FileCard.Root

The card container with rounded border and shadow.

Prop	Type	Default	Description

FileCard.Thumbnail

Left-side thumbnail area (176x104px, gray background).

Prop	Type	Default	Description

FileCard.Image

An image thumbnail that fills the thumbnail area.

Prop	Type	Default	Description
`src`	`string`	-	The image source URL.

FileCard.Video

A video thumbnail with a centered video icon overlay.

Prop	Type	Default	Description
`src`	`string`	-	The video thumbnail image URL.

FileCard.Audio

An audio thumbnail with a speaker icon.

Prop	Type	Default	Description

FileCard.Content

Right-side content area containing body and actions.

Prop	Type	Default	Description

FileCard.Body

Stacks filename, meta, and hint vertically with gap-1 (4px). Use for completed states.

Prop	Type	Default	Description

FileCard.UploadBody

Stacks info group and progress/retry vertically with gap-3 (12px). Use for uploading/failed states.

Prop	Type	Default	Description

FileCard.InfoGroup

Groups name and status with gap-1.5 (6px). Use inside UploadBody.

Prop	Type	Default	Description

FileCard.Name

The filename text (truncated).

Prop	Type	Default	Description

FileCard.Meta

Secondary info like file size.

Prop	Type	Default	Description

FileCard.Hint

Tertiary info like upload date or size recommendations.

Prop	Type	Default	Description

FileCard.Status

Upload status indicator with icon.

Prop	Type	Default	Description
`status`	`'uploading' \| 'failed'`	-	The upload status. Shows a spinner for uploading, error icon for failed.

FileCard.Progress

A progress bar for upload progress.

Prop	Type	Default	Description
`value`	`number`	`0`	Current progress value.
`max`	`number`	`100`	Maximum progress value.

FileCard.RemoveButton

A red outline button for removing the file.

Prop	Type	Default	Description

FileCard.DownloadButton

A subtle download icon button for downloading files.

Prop	Type	Default	Description

FileCard.CloseButton

A subtle close (x) button for canceling uploads.

Prop	Type	Default	Description

FileCard.RetryLink

A red underlined link for retrying failed uploads.

Prop	Type	Default	Description

FileCard.CompactRoot

Compact card container without thumbnail area. Supports error border.

Prop	Type	Default	Description
`error`	`boolean`	`false`	When true, applies a red error border.

FileCard.CompactContent

Row layout for icon, text body, and action button.

Prop	Type	Default	Description

FileCard.CompactBody

Stacks name and description vertically with gap-1.

Prop	Type	Default	Description

FileCard.CompactErrorBody

Wraps CompactBody and RetryLink with gap-2. Use for failed states.

Prop	Type	Default	Description

FileCard.CompactDescription

Inline row for meta, dot separator, and status.

Prop	Type	Default	Description

FileCard.Dot

A dot separator for inline descriptions.

Prop	Type	Default	Description

FileCard.CompactStatus

Status indicator with icon for compact variant.

Prop	Type	Default	Description
`status`	`'uploading' \| 'completed' \| 'failed'`	-	The upload status. Shows spinner, checkmark, or error icon.

FileCard.DeleteButton

A subtle delete bin icon button for removing files.

Prop	Type	Default	Description