Ballmac UI home

Lock ScreenPRO

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.

7/7 checksv1.0.1Updated Oct 11, 2026Ships with a test
What changed
  1. 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.

Update without losing your edits

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

  1. 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.

  2. 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.local
    BALLMAC_LICENSE_KEY=your-licence-key
  3. Add 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

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

Quality scorecard

7/7

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 (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.