Ballmac UI home

Media

A picture slot: reserves the space, lazy-loads, takes a URL, an image with required alt text and a dark-mode file, or your own element, and falls back to artwork if there is no image or it fails.

6/6 checksv1.0.1Updated Oct 11, 2026Ships with a test
What changed
  1. 1.0.1 Oct 11, 2026isMediaImage and the MediaImage type moved to the new media-image helper so server components can call it; both are still exported from here. Adds media-image as a dependency.

Update without losing your edits

The dashboard showing this month's revenue
A URL with alt text
Any element
Your own element
Your screenshot here
No image: the artwork

Installation

$ pnpm dlx shadcn@latest add @ballmac/media

Usage

import { Media, isMediaImage } from "@/components/ballmac/media"

The full example is in the Code tab above.

Examples

A different file in dark mode

The inbox in the current colour scheme

Switch the theme to swap the file.

API reference

PropTypeDefault
media

The picture, or your own element. Leave it out to show `fallback`.

MediaSource | null—
alt

Describes a picture passed as a plain URL. Required for informative images; use "" for decoration.

string—
fallback

What shows when there is no `media` or the file fails to load. Usually the block's built-in artwork.

React.ReactNode—
aspect

Reserves the box before the image loads, so the page does not jump. `auto` keeps the image's own proportions.

MediaAspect"auto"
fit

`cover` fills and crops, `contain` shows all of it, `fill` stretches.

"cover" | "contain" | "fill""cover"
priority

Above the fold: load now and with high priority instead of lazily.

booleanfalse
fill

Fill a parent that has its own size (an absolutely positioned panel) instead of reserving space by aspect ratio.

boolean—
frame

A card frame (rounded corners, border, soft shadow) around a real image or element. The built-in artwork keeps its own.

booleanfalse
onImageError

Called when the file fails to load (the fallback is shown).

() => void—

Also accepts the standard attributes of its root element.

Accessibility

KeyAction
Screen readersInformative images need alt text; alt="" marks decoration. A URL without alt logs a warning in development
LayoutA fixed aspect ratio reserves the space, so nothing jumps when the file arrives

Quality scorecard

6/6

Every applicable check passes

Measured in Chromium 153.0.8010.12 on October 19, 2026, on version 1.0.1, across 2 examples.

How we measure
  • Passed: Accessibility scan

    No serious or critical issues in light and dark, on a phone and a desktop (axe-core 4.13.0, WCAG 2.1 AA and best-practice rules).

  • Passed: Small screens

    No sideways scrolling at 360, 390 or 1280 px wide.

  • Passed: Reduced motion

    No endless animation to begin with.

  • Passed: Right to left

    Mirrors correctly in Arabic, Hebrew, Persian and Urdu layouts (0% of elements off the mirror, limit 15%).

  • Passed: Clean console

    No console errors or React hydration errors while loading.

  • Not applicable: Keyboard

    Static content: nothing to focus.

  • Not applicable: Loading, empty and error

    Does not show data or take submissions.

  • Passed: Automated tests

    Covered by media.test.tsx.

  • For information: Footprint

    2.4 KB of source (gzip) in 1 file. No extra npm packages.

Automated checks find a subset of problems and do not replace testing with a screen reader and a keyboard in your own app. What they miss.

Use with AI

Pass media as a URL (with alt), an object { src, alt, srcDark? }, or any element such as a next/image. aspect reserves the box (video, photo, square, wide, portrait or '3/2'); fit is cover | contain | fill; priority loads an above-the-fold image eagerly. fallback shows when there is no media or the file fails. With the shadcn MCP server set up (guide), ask your agent:

Add the Ballmac UI Media (@ballmac/media) to this project with the shadcn MCP, then use it where it fits.

Use it for

  • Any place a product screenshot, photo, cover or avatar goes
  • Blocks and templates that ship with generated artwork but should accept the buyer's own image

Not for

  • Icons (use an icon component)
  • Animated or interactive content that is not an image: pass it as an element

Registry JSON: https://ui.ballmac.com/r/media.json

Credits

Free to use in personal and commercial projects.

npm
None

Ballmac UI Pro

Need the whole screen, not one piece?

311 premium blocks (dashboards, settings, calendars, mail, shops, onboarding), a private shadcn registry and Figma tokens. Blocks that show data come with loading, empty and error states built in.

Not ready? Try three Pro blocks free

Leave your email and the blocks appear right here, ready to copy. Yours to use in any project.