DroppyKit 1.0.2

Build Droplets for Droppy.

A Droplet draws on the same surfaces Droppy's own features do, in SwiftUI, against this SDK.

DroppyKit: custom widgets, live activities and HUDs in Droppy, the Dynamic Island and shelf for Mac.

A Droplet is an extension that lives inside Droppy. It draws on the same surfaces Droppy's own features do — the notch, the shelf, the lock screen — and it is written in SwiftUI, against this SDK.

Droplets are native code running in Droppy's process, so the Store is review-and-sign: you build against DroppyKit, submit an open-source repository, and a reviewed build is signed and published. Nothing loads unsigned, and no droplet ships without someone having read it.

The surfaces you can build

SurfaceWhat it isProtocol
Shelf widgetA card on the expanded shelf, alone or sharing the rowShelfWidgetProviding
Live activityA compact row beside the notch, plus its expanded detailLiveActivityProviding
Expanded surfaceA takeover on the notch, for something that needs the roomExpandedSurfaceProviding
Settings paneYour droplet's own page inside Droppy's SettingsSettingsPaneProviding
HUDA transient message on the notchHUDPresenting
Lock screen rowOne line on Droppy's lock surfaceLockScreenStatusProviding
Menu bar extraAn item beside Droppy's ownMenuBarExtraProviding

You pick the ones you need. A droplet that only draws a shelf widget is a perfectly good droplet.

What a droplet is made of

  • A Swift package that builds a dynamic library and links DroppyKit.
  • A droplet.json manifest — see DropletManifest — naming the droplet, the surfaces it provides, the capabilities it needs, and who made it.
  • An Icon Composer document, which is required. See DropletIcon.
  • A creator avatar, also required, which is the round mark beside your droplet's name in the Store. See DropletCreatorAvatar.

Trying it without installing anything

DroppyKitHarness opens your droplet in Droppy's Settings panel — the real one, built from the app's own source — with a page per surface, a switch per capability, and a running list of everything your droplet asks the host to do. It never touches the system, so it runs happily alongside Droppy itself.

import DroppyKit
import DroppyKitHarness

@main
struct WorldClockHarness: DropletHarnessApp {
    static func makeDroplet() -> any Droplet { WorldClockDroplet() }
}

Start here

Building a droplet

Artwork

Testing

Publishing

Entry point

Manifest

Host services

Design system

Versioning

Start here

Add the packageSwift Package Manager, Xcode, and why a bare swift build is wrong. Your first dropletFrom an empty folder to a droplet running in the harness. The manifestdroplet.json, the bundle it becomes, and the capabilities you declare.

Build a surface

Design guidelinesHow a droplet looks like part of Droppy instead of a guest in it. Shelf widgetsA card on the expanded shelf, alone or sharing the row. Live activitiesA compact row beside the notch, and its expanded detail. Expanded surfacesA takeover on the notch, for something that needs the whole shelf. Settings panesYour droplet's own page inside Droppy's Settings. The iconThe Icon Composer document every droplet has to ship.

Test and ship

The harnessDroppy's real Settings panel, running your droplet, with nothing installed. Host supportWhich surfaces the shipping Droppy mounts, and what a refusal means. SubmittingReview, signing, and how a droplet reaches somebody's Mac.

Reference

API referenceEvery public type in DroppyKit, 123 of them.