Ballmac UI home

Lock Screen

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.

Welcome back, Alex

Thu Oct 1

9:41

Alex Morgan

Hint: the password is “hello”

Type a wrong password to see it shake, then “hello” to unlock.

Installation

$ pnpm dlx shadcn@latest add @ballmac/lock-screen

Usage

import { LockScreen } from "@/components/ballmac/lock-screen"

The full example is in the Code tab above.

Examples

iOS in a phone

Home Screen

Thursday, October 1

9:41

Messagesnow

Sam

Are we still on for dinner tonight? I booked the table by the window.

Calendar9m ago

Design review

Starts in 15 minutes · Room 4B

API reference

PropTypeDefault
variant

"mac" shows a password field under the user's avatar; "ios" shows notifications and a swipe-up unlock.

"mac" | "ios""mac"
locked

Controlled state. While true the lock screen covers its positioned parent.

boolean—
defaultLocked

Initial state when uncontrolled.

booleantrue
onLockedChange

Called with the new state when the screen unlocks.

(locked: boolean) => void—
time

Time to show, such as "9:41". Omit for a live clock.

string—
date

Date to show, such as "Thursday, October 1". Omit for the live date.

string—
name

Name under the avatar (mac).

string"Alex Morgan"
avatar

Replaces the default avatar (mac): an image, icon or initials.

React.ReactNode—
password

The correct password (mac). Without it, any entry unlocks.

string—
onUnlock

Extra check on the entered password (mac). Return false to reject it.

(password: string) => boolean | void—
hint

Hint under the field (mac).

string—
wallpaper

Replaces 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—
children

Notifications on iOS, or controls along the bottom on mac.

React.ReactNode—

Also accepts the standard attributes of its root element.

Accessibility

KeyAction
TabReaches the password field and the Unlock button
EnterSubmits the password
Wrong passwordAnnounced as an alert and the field shakes (no shake with reduced motion)
Reduced motionFade instead of slide, blur and scale; iOS shows an Unlock button

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/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: https://ui.ballmac.com/r/lock-screen.json

Credits

Free to use in personal and commercial projects.