Skip to main content

DownloadCard Component

A reusable card component for downloadable files. Shows the file name, a download button, and optionally the file size, an expandable file-tree preview of archive contents, and a clickable preview for images, PDFs, and code files. Use it at the top of pages for primary downloads or inline within content.

Features​

  • File name and download button: Clear, accessible download action
  • Optional file size badge: Human-readable size shown beside the file name
  • Optional title and description: Additional context above the file name
  • Expandable file tree: Collapsible preview of archive contents (folders are toggleable)
  • Clickable preview: Auto-detected from file extension, with three modes:
    • Images (.png, .jpg, .avif, .svg, etc.) open in a lightbox modal
    • PDFs (.pdf) open in an iframe modal
    • Code (.js, .ts, .py, .css, .json, .md, etc.) expand inline with syntax label
  • Dark mode: Full light/dark mode support using Infima variables
  • Responsive: Stacks vertically on mobile screens
  • Accessible: Keyboard navigation, aria-expanded attributes, Escape to close, focus-visible outlines

Basic Usage​

Import the component and use it in your MDX files:

import DownloadCard from '@site/src/theme/MDXComponents/DownloadCard';

<DownloadCard
  downloadUrl="/downloads/my-file.zip"
  fileName="my-file.zip"
/>

With Title and Description​

<DownloadCard
  downloadUrl="/downloads/cursor-workspace-rules-template.zip"
  fileName="cursor-workspace-rules-template.zip"
  title="Cursor Workspace Rules Template"
  description="Ready-to-use .cursorrules folder you can drop into a new repo."
/>

With File Size​

Add a fileSize prop to display a small badge next to the file name:

<DownloadCard
  downloadUrl="/downloads/cursor-workspace-rules-template.zip"
  fileName="cursor-workspace-rules-template.zip"
  title="Cursor Workspace Rules Template"
  fileSize="4 KB"
/>

With File Structure​

Pass a structure array to show an expandable tree of the archive contents. Each node has a name and optional children array for folders:

<DownloadCard
  downloadUrl="/downloads/cursor-workspace-rules-template.zip"
  fileName="cursor-workspace-rules-template.zip"
  title="Cursor Workspace Rules Template"
  fileSize="4 KB"
  description="Ready-to-use .cursorrules folder you can drop into a new repo."
  structure={[
    { name: '.cursorrules-EDITABLE/', children: [
      { name: 'mcp.json' },
      { name: 'rules/', children: [
        { name: 'README.md' },
        { name: 'style/', children: [{ name: 'RULE.md' }] },
        { name: 'documentation/', children: [{ name: 'RULE.md' }] },
      ]},
    ]},
  ]}
/>

Folders display a chevron and can be expanded or collapsed by clicking. The tree starts fully expanded.

With Children​

Pass additional content as children; it renders in a bordered area below the card body:

<DownloadCard
  downloadUrl="/downloads/cursor-workspace-rules-template.zip"
  fileName="cursor-workspace-rules-template.zip"
  title="Cursor Workspace Rules Template"
>

After downloading, unzip and copy the `.cursorrules-EDITABLE` folder into your new repository root.

</DownloadCard>

Preview​

Preview is auto-detected from the file extension. When a previewable file type is detected, a "Preview" button appears next to the Download button automatically. No extra props needed.

File typeExtensionsBehaviour
Image.png, .jpg, .avif, .svg, .gif, .webp, etc.Opens in a lightbox modal
PDF.pdfOpens in an iframe modal
Code.js, .ts, .py, .css, .json, .md, .html, etc.Expands inline within the card

You can override auto-detection with the preview prop:

{/* Force preview off for a .js file */}
<DownloadCard
  downloadUrl="/downloads/script.js"
  fileName="script.js"
  preview={false}
/>

{/* Force preview on for an unusual extension */}
<DownloadCard
  downloadUrl="/downloads/config.toml"
  fileName="config.toml"
  preview={true}
/>

All modals close with Escape or by clicking the backdrop. Code previews scroll within a max-height container.

Live Examples​

These are real, working DownloadCard components. Click Preview to try the preview feature, or Download to verify the download.

Code file (inline preview)​

Click Preview to expand the source code inline.

text-highlighting.js
Download

PDF (modal preview)​

Click Preview to open the PDF in an iframe overlay.

DENI Initial PresentationDENI - Initial Presentation.pdf19 MBExample PDF document used to test the DownloadCard component.
Download

Image (lightbox preview)​

Click Preview to open the image in a lightbox.

Test Imagetest-image1.avif25 KB
Download
Cursor Workspace Rules Templatecursor-workspace-rules-template.zip4 KBReady-to-use .cursorrules folder you can drop into a new repo.
Download

With children content​

Text Highlighting Scripttext-highlighting.js4.4 KBJavaScript utility for highlighting text on a page.
Download

After downloading, include the script in your page:

<script src="text-highlighting.js"></script>

API Reference​

Props​

PropTypeDefaultDescription
downloadUrlstring(required)Path or full URL to the downloadable file
fileNamestring(required)Display file name
titlestringundefinedHeading shown above the file name
descriptionstringundefinedShort description below the file name
fileSizestringundefinedHuman-readable file size badge, e.g. "4 KB"
structureObject[]undefinedFile-tree data for an expandable archive preview
previewbooleanauto-detectedEnable/disable preview button (auto-detected from file extension if omitted)
childrenReactNodeundefinedAdditional content rendered below the card

Structure Node Shape​

interface TreeNode {
  /** Display name (use trailing / for folders by convention) */
  name: string;
  /** Child nodes; presence marks this node as a folder */
  children?: TreeNode[];
}

Best Practices​

When to Use​

  • Linking to downloadable assets (ZIP, PDF, templates, etc.)
  • Providing archive contents preview so users know what they are getting
  • Prominent download CTAs at the top of a guide or setup page

Keep It Focused​

  • One download per card (for multiple downloads, use multiple cards)
  • Use title for human-friendly context, fileName for the exact file name
  • Add structure only when users benefit from seeing internal contents (e.g. template archives)

Placement​

  • Top of page: Before the main content, so users can download immediately
  • Related documentation section: At the bottom alongside related links
  • Inline: Within instructions where the download is a specific step

Setup in New Repos​

To add the DownloadCard component to a new Docusaurus repo:

  1. Copy component files:

    cp -r docusaurus/src/theme/MDXComponents/DownloadCard /path/to/new-repo/src/theme/MDXComponents/

  2. Import in your MDX files:

    import DownloadCard from '@site/src/theme/MDXComponents/DownloadCard';

  3. Start using:

    <DownloadCard
      downloadUrl="/downloads/my-template.zip"
      fileName="my-template.zip"
      title="My Template"
    />

The component is fully self-contained with styles included.