A full-screen lock screen in two flavors: macOS (live clock, avatar, password field that shakes when wrong) and iOS (clock, notification stack, flashlight and camera, swipe up to unlock). Hydration-safe clock.
What changed
- 1.0.1 Oct 11, 2026Fixes a crash when it is rendered from a server component: isMediaImage now comes from the new media-image helper, not from the client-only media file. Adds media-image as a dependency.
The source is part of Ballmac UI Pro.
Log in with your licence key to read and copy it here, or install it through the shadcn CLI or the MCP server. You own the code once it is in your project.
$49 once regular price $99for this and every other Pro item. Tax included.Money back if it does not work.
Installation
Get a Pro licence key.
The source is part of Ballmac UI Pro.
Log in with your licence key to read and copy it here, or install it through the shadcn CLI or the MCP server. You own the code once it is in your project.
$49 once
regular price $99for this and every other Pro item. Tax included.Money back if it does not work.Once per project: add the Pro registry and your licence key.
components.json{ "registries": { "@ballmac": "https://ui.ballmac.com/r/{name}.json", "@ballmac-pro": { "url": "https://ui.ballmac.com/r/pro/{name}.json", "headers": { "Authorization": "Bearer ${BALLMAC_LICENSE_KEY}" } } } }.env.localBALLMAC_LICENSE_KEY=your-licence-keyAdd it.
$ pnpm dlx shadcn@latest add @ballmac-pro/lock-screen
Usage
import { LockScreen } from "@/components/ballmac/lock-screen"The full example is in the Code tab above.
Examples
iOS in a phone
The source is part of Ballmac UI Pro.
Log in with your licence key to read and copy it here, or install it through the shadcn CLI or the MCP server. You own the code once it is in your project.
$49 once regular price $99for this and every other Pro item. Tax included.Money back if it does not work.
API reference
| Prop | Type | Default |
|---|---|---|
variant"mac" shows a password field under the user's avatar; "ios" shows notifications and a swipe-up unlock. | "mac" | "ios" | "mac" |
lockedControlled state. While true the lock screen covers its positioned parent. | boolean | — |
defaultLockedInitial state when uncontrolled. | boolean | true |
onLockedChangeCalled with the new state when the screen unlocks. | (locked: boolean) => void | — |
timeTime to show, such as "9:41". Omit for a live clock. | string | — |
dateDate to show, such as "Thursday, October 1". Omit for the live date. | string | — |
nameName under the avatar (mac). | string | "Alex Morgan" |
avatarReplaces the default avatar (mac): an image, icon or initials. | React.ReactNode | — |
passwordThe correct password (mac). Without it, any entry unlocks. | string | — |
onUnlockExtra check on the entered password (mac). Return false to reject it. | (password: string) => boolean | void | — |
hintHint under the field (mac). | string | — |
wallpaperReplaces the default wallpaper. An image URL, an object with alt text and a dark-mode file, or an element that fills it; text stays white, so keep it dark enough. | MediaSource | — |
childrenNotifications on iOS, or controls along the bottom on mac. | React.ReactNode | — |
Also accepts the standard attributes of its root element.
Accessibility
| Key | Action |
|---|---|
| Tab | Reaches the password field and the Unlock button |
| Enter | Submits the password |
| Wrong password | Announced as an alert and the field shakes (no shake with reduced motion) |
| Reduced motion | Fade instead of slide, blur and scale; iOS shows an Unlock button |
Quality scorecard
Every applicable check passes
Measured in Chromium 153.0.8010.12 on October 19, 2026, on version 1.0.1, across 2 examples.
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 (2% of elements off the mirror, limit 15%).
Passed: Clean console
No console errors or React hydration errors while loading.
Passed: Keyboard
7 tab stops, each showing a visible change when it takes focus. 4 documented keys.
Not applicable: Loading, empty and error
Does not show data or take submissions.
Passed: Automated tests
Covered by lock-screen.test.tsx.
For information: Footprint
4.1 KB of source (gzip) in 1 file. Installs motion, lucide-react.
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
<LockScreen variant="mac" password="hello" /> fills its positioned parent until unlocked. variant="ios" takes notifications as children and unlocks by swiping up or pressing the button. Control with locked / onLockedChange. With the shadcn MCP server set up (guide), ask your agent:
Add the Ballmac UI Lock Screen (@ballmac-pro/lock-screen) to this project with the shadcn MCP, then use it where it fits.
Use it for
- Mac or phone UI demos with a login moment
- Idle or session-timeout screens
Not for
- Real authentication: the password prop is for demos, check credentials on a server
Registry JSON (needs your licence key): https://ui.ballmac.com/r/pro/lock-screen.json
Credits
Covered by the Ballmac UI Pro license.
Pairs well with
Phone Frame
A modern phone drawn in CSS: titanium band, side buttons, Dynamic Island, status bar and home indicator. Children render as the screen, laid out at a phone resolution and scaled to fit.
Notification Stack
macOS Notification Center cards: collapsed, the newest sits in front with two peeking behind; click or press Enter to spring the stack open. New cards slide in from the top; each can be dismissed.
Mac Window
macOS window chrome: traffic lights whose glyphs appear on hover, a centered title or unified toolbar, an optional translucent sidebar with vibrancy, and active and inactive appearances.
Menu Bar
A translucent macOS menu bar on Radix Menubar: a bold app menu, menus with key equivalents, submenus and checkmarks, a status area with icon buttons and a hydration-safe live clock.