iOS Widgets and Live Activities
Widget and Live Activity services, with iOS widget views
Home Screen widgets and Live Activities use One.Widgets and One.LiveActivities. Their iOS implementation needs native.app.ios.widgets and a new iOS build; calls without that configured bridge throw. Android reports the iOS-only limit for widget writes, activity starts, updates, endings, and push-token listener registration. pushToken returns null. On web, widget writes and activity updates or endings have no effect, push tokens return null, and listener removers do nothing. Starting an activity on web rejects with LiveActivities.<verb> needs an iOS or Android build. The iOS view tree remains under One.iOS.WidgetUI.
Widgets
One.Widgets writes the widget’s content.
| Function | Signature |
|---|---|
write | (data: { title: string; value: string; subtitle: string }) => Promise<void> |
writeView | (view: ReactNode) => Promise<void> |
write sets plain text content; writeView renders a WidgetUI tree
(see below) into the widget.
LiveActivities
One.LiveActivities manages Live Activities. State is { status: string; value: string }; push token events are { id: string; token: string }.
| Function | Signature |
|---|---|
start | (title: string, state, push?: boolean) => Promise<string> (resolves the activity id) |
startView | (title: string, view: ActivityView, push?: boolean) => Promise<string> |
update | (id: string, state) => Promise<void> |
updateView | (id: string, view: ActivityView) => Promise<void> |
end | (id: string) => Promise<void> |
pushToken | (id: string) => Promise<string | null> |
onPushToken | (listener: (event) => void) => () => void (returns an unsubscribe function) |
push opts into push updates. An ActivityView places a WidgetUI tree in
each Live Activity region:
| ActivityView | Type | Description |
|---|---|---|
lockScreen (required)ReactNodeThe Lock Screen banner. | ReactNode | The Lock Screen banner. |
compactLeadingReactNodeLeft of the camera in the compact Dynamic Island. | ReactNode | Left of the camera in the compact Dynamic Island. |
compactTrailingReactNodeRight of the camera in the compact Dynamic Island. | ReactNode | Right of the camera in the compact Dynamic Island. |
minimalReactNodeThe Dynamic Island when another activity shares it. | ReactNode | The Dynamic Island when another activity shares it. |
expandedLeadingReactNodeThe expanded Dynamic Island, leading side. | ReactNode | The expanded Dynamic Island, leading side. |
expandedTrailingReactNodeThe expanded Dynamic Island, trailing side. | ReactNode | The expanded Dynamic Island, trailing side. |
expandedBottomReactNodeThe expanded Dynamic Island, below the sides. | ReactNode | The expanded Dynamic Island, below the sides. |
WidgetUI
One.iOS.WidgetUI builds widget content. Each element takes a style.
| Element | Props |
|---|---|
Text, VStack, HStack, ZStack | children |
Spacer, Divider | none |
Image | systemName |
Progress, Gauge | value, total |
Circle, Rectangle, RoundedRectangle | fill, cornerRadius |
Link | url, children |
| WidgetStyle | Type | Description |
|---|---|---|
colorstringThe text and symbol color. | string | The text and symbol color. |
backgroundColorstringThe fill behind the element. | string | The fill behind the element. |
fontSizenumberThe text size in points. | number | The text size in points. |
fontWeight"regular" | "medium" | "semibold" | "bold"The text weight. | "regular" | "medium" | "semibold" | "bold" | The text weight. |
fontDesign"default" | "rounded" | "serif" | "monospaced"The system font design. | "default" | "rounded" | "serif" | "monospaced" | The system font design. |
paddingnumberSpace inside the element on every side. | number | Space inside the element on every side. |
borderRadiusnumberRounds the background. | number | Rounds the background. |
spacingnumberThe gap between a stack's children. | number | The gap between a stack's children. |
widthnumberA fixed width. | number | A fixed width. |
heightnumberA fixed height. | number | A fixed height. |
opacitynumberFrom 0 to 1. | number | From 0 to 1. |
lineLimitnumberThe most lines a Text shows. | number | The most lines a Text shows. |
alignment"leading" | "center" | "trailing"How a stack aligns its children. | "leading" | "center" | "trailing" | How a stack aligns its children. |
import { One } from 'one'
await One.Widgets.writeView( <One.iOS.WidgetUI.VStack> <One.iOS.WidgetUI.Text>Next train</One.iOS.WidgetUI.Text> <One.iOS.WidgetUI.Text>4 min</One.iOS.WidgetUI.Text> </One.iOS.WidgetUI.VStack>)
const id = await One.LiveActivities.start('Trip', { status: 'Boarding', value: 'Gate 12' })await One.LiveActivities.update(id, { status: 'Departed', value: 'On time' })await One.LiveActivities.end(id)Current limits
On an iOS 27 simulator, Home Screen widgets render and update both typed payloads and JSX content. Live Activities render, update and end with both forms on the Lock Screen. Expanded Dynamic Island content has been verified with JSX. Compact and minimal Dynamic Island presentations, scalar content in the Dynamic Island, and a physically locked device remain unverified.
The app and WidgetKit extension must use the same App Group and have the required signing capabilities. A successful write alone does not prove that the system widget has rendered the new content.
Edit this page on GitHub.