Ballmac UI home

Widgets

Desktop widgets in three sizes: weather with a sky gradient, hourly strip and daily ranges; a calendar with a month grid and events; a battery widget with rings. They scale with their width and use UTC dates.

Cupertino, 72 degrees, Partly Cloudy. High 78, low 61.

Thursday, October 1, 2026

  • Design review10:30 – 11:15 AM
  • iPhone, 82 percent, charging
  • Watch, 54 percent
  • Earbuds, 17 percent
  • MacBook, 96 percent

Installation

$ pnpm dlx shadcn@latest add @ballmac/widgets

Usage

import { Widget, WeatherWidget, CalendarWidget, BatteryWidget } from "@/components/ballmac/widgets"

The full example is in the Code tab above.

Examples

All three sizes

Cupertino, 72 degrees, Partly Cloudy. High 78, low 61.

Thursday, October 1, 2026

  • Design review10:30 – 11:15 AM

Oslo, -2 degrees, Snow. High 1, low -6.

Cupertino, 72 degrees, Clear. High 78, low 61.

  • iPhone, 82 percent, charging
  • Watch, 54 percent
  • Earbuds, 17 percent
  • MacBook, 96 percent

API reference

<Widget>

PropTypeDefault
size

Which size the widget draws at. Set the width with `className` (a small widget is about 10rem wide).

WidgetSize"small"
label*

Accessible name of the widget.

string—
surfaceClassName

Class names for the widget's surface (background and text color). `className` sizes and places the widget.

string—

<WeatherWidget>

PropTypeDefault
city*

Place name.

string—
temperature*

Current temperature, in degrees.

number—
condition

Current sky. Chooses the gradient, icon and wording.

WeatherCondition"clear"
high*

Today's high.

number—
low*

Today's low.

number—
hourly

Upcoming hours, shown on medium and large widgets.

HourlyForecast[][]
daily

Upcoming days, shown on the large widget.

DailyForecast[][]

<CalendarWidget>

PropTypeDefault
date*

The day to show, as an ISO date such as "2026-10-01". Read as UTC, so every viewer sees the same day.

string—
events

Events on that day, in order.

CalendarEvent[][]

<BatteryWidget>

PropTypeDefault
devices*

Devices and their charge. Small shows four, medium four, large lists them all.

BatteryDevice[]—

Also accepts the standard attributes of its root element.

Accessibility

KeyAction
Screen readersEach widget is a named section with a one-sentence summary; decorative icons are hidden
ColorCharge level and conditions are also given in words

Use with AI

<WeatherWidget city temperature condition high low hourly daily size />, <CalendarWidget date="2026-10-01" events size />, <BatteryWidget devices size />. Width is set with className; height follows the size (small square, medium 2:1, large near-square). <Widget> is the bare frame. With the shadcn MCP server set up (guide), ask your agent:

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

Use it for

  • Dashboards that want glanceable cards
  • Desktop and Today-view mockups

Not for

  • Interactive charts (chart)
  • Live data fetching: pass data in

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

Credits

Free to use in personal and commercial projects.