feat: add supplemental activity families support for iOS 18+ #13

mrevanzak · 2026-01-14T19:29:29Z

Summary

Add support for Apple's supplementalActivityFamilies modifier (iOS 18+) enabling Live Activities on watchOS Smart Stack and CarPlay
Introduce supplementalActivityFamilies.small variant in TypeScript API with automatic fallback to lockScreen content
Require explicit opt-in via plugin config liveActivity.supplementalActivityFamilies: ["small"]

Changes

TypeScript

Add supplementalActivityFamilies.small to LiveActivityVariants type
Add sup_sm JSON key to renderer output
Update renderer to handle supplemental regions

Swift

Add supplementalSmall case to VoltraRegion enum
Add VoltraAdaptiveLockScreenView with @Environment(\.activityFamily) detection
iOS 18+ availability checks with graceful fallback for older versions

Plugin

Add LiveActivityConfig type with supplementalActivityFamilies option
Generate VoltraWidgetWithSupplementalActivityFamilies wrapper when configured
Add validation for activity family configuration

Usage

{
  "expo": {
    "plugins": [
      ["voltra", {
        "groupIdentifier": "group.com.example",
        "liveActivity": {
          "supplementalActivityFamilies": ["small"]
        }
      }]
    ]
  }
}

 useLiveActivity({
  ...,
  supplementalActivityFamilies: {
    small: <CompactWatchView />  
  }
})

Requirements

Feature	Minimum iOS
watchOS Smart Stack	iOS 18.0
CarPlay Dashboard	iOS 26.0

Example

WatchOS

…ptive view

- Add renderer tests for supplemental.small variant serialization - Add plugin tests for validation and widget bundle generation - Add WatchLiveActivity example demonstrating supplemental.small - Enable supplementalFamilies in example app config

@unknown

Swift syntax requires @unknown default to be its own case, cannot combine with other patterns.

- Add comprehensive guide at development/supplemental-activity-families.md - Update plugin-configuration.md with liveActivity config section - Add navigation entry in development/_meta.json - Reference supplemental families in developing-live-activities.md

vercel · 2026-01-14T19:29:34Z

@mrevanzak is attempting to deploy a commit to the Callstack Team on Vercel.

A member of the Team first needs to authorize it.

mrevanzak · 2026-01-14T19:31:55Z

closed #11

mrevanzak · 2026-01-14T19:33:28Z

@V3RON

V3RON · 2026-01-14T19:40:31Z

I'm going to go through it tomorrow! 👀

Align API naming with Apple's native .supplementalActivityFamilies() modifier. Changes: - TypeScript: supplemental -> supplementalActivityFamilies in variants - Plugin config: supplementalFamilies -> supplementalActivityFamilies - Swift: supplementalSmall -> supplementalActivityFamiliesSmall - JSON key: sup_sm -> saf_sm - Generated Swift wrapper: VoltraWidgetWithSupplementalActivityFamilies - Update all tests and documentation

ios/target/VoltraWidget.swift

V3RON · 2026-01-15T09:36:31Z

ios/target/VoltraWidget.swift

+/// A view that adapts its content based on the activity family environment
+/// - For .small (watchOS/CarPlay): Uses supplementalActivityFamiliesSmall content if available, falls back to lockScreen
+/// - For .medium (iPhone lock screen) and unknown: Always uses lockScreen


Now I understand this better. Apple’s docs aren't very clear about what behavior to expect 👌

V3RON · 2026-01-15T09:37:43Z

plugin/src/types/activity.ts

+ * Supported supplemental activity families (iOS 18+)
+ * These enable Live Activities to appear on watchOS Smart Stack and CarPlay
+ */
+export type ActivityFamily = 'small'


What about 'medium'?

medium is the default one that we have without any config @V3RON. the lockscreen one. so no need to specify it again. Even if we pass [.small, .medium], it will have the same effect as [.small].

plugin/src/types/plugin.ts

website/docs/development/supplemental-activity-families.md

V3RON · 2026-01-15T09:44:55Z

website/docs/development/supplemental-activity-families.md

+Starting with iOS 18, Live Activities can appear on additional surfaces beyond the iPhone lock screen and Dynamic Island:
+
+- **watchOS Smart Stack** (iOS 18+) - Appears on paired Apple Watch
+- **CarPlay Dashboard** (iOS 26+) - Appears on CarPlay displays


Is CarPlay somehow connected to supplemental activity families? I think it just works with the default configuration.

@V3RON

https://developer.apple.com/download/files/CarPlay-Developer-Guide.pdf

I'm going to verify this in my car later today 👀

alright haha

V3RON · 2026-01-15T09:46:05Z

plugin/src/features/ios/files/swift/widgetBundle.ts

+function generateVoltraWidgetWrapper(familiesSwift: string): string {
+  return dedent`
+    // MARK: - Live Activity with Supplemental Activity Families
+
+    struct VoltraWidgetWithSupplementalActivityFamilies: Widget {
+      private let wrapped = VoltraWidget()
+
+      var body: some WidgetConfiguration {
+        if #available(iOS 18.0, *) {
+          return wrapped.body.supplementalActivityFamilies([${familiesSwift}])
+        } else {
+          return wrapped.body
+        }
+      }
+    }
+  `
+}


Note for myself: make sure to format generated code correctly, so it's more pleasant to read.

V3RON · 2026-01-16T07:52:20Z

There may be cases where we want to enable Watch only for a subset of Live Activities. In the current implementation, it's either none or all-in. I'm wondering if we should refactor this so we have two configs for Live Activities: one for "non-Watch" and another for "Watch-enabled". We could then target one of them based on the config parameter the user passes when displaying the Live Activity. This would also work remotely. WDYT?

var body: some Widget {
        // Config 1: Standard (No supplemental families)
        ActivityConfiguration(for: DeliveryAttributes.self) { context in
            DeliveryLockScreenView(context: context)
        } dynamicIsland: { context in
            DynamicIsland { ... } // Your Dynamic Island code
        }

        // Config 2: Watch Enabled (Adds .small / .medium)
        ActivityConfiguration(for: DeliveryAttributesWithWatch.self) { context in
            DeliveryLockScreenView(context: context) // You can reuse the same view code
        } dynamicIsland: { context in
             DynamicIsland { ... } // Reuse same Island code
        }
        .supplementalActivityFamilies([.small, .medium]) // <--- The specific difference
    }

mrevanzak · 2026-01-16T12:18:26Z

There may be cases where we want to enable Watch only for a subset of Live Activities. In the current implementation, it's either none or all-in. I'm wondering if we should refactor this so we have two configs for Live Activities: one for "non-Watch" and another for "Watch-enabled". We could then target one of them based on the config parameter the user passes when displaying the Live Activity. This would also work remotely. WDYT?
var body: some Widget {
        // Config 1: Standard (No supplemental families)
        ActivityConfiguration(for: DeliveryAttributes.self) { context in
            DeliveryLockScreenView(context: context)
        } dynamicIsland: { context in
            DynamicIsland { ... } // Your Dynamic Island code
        }

        // Config 2: Watch Enabled (Adds .small / .medium)
        ActivityConfiguration(for: DeliveryAttributesWithWatch.self) { context in
            DeliveryLockScreenView(context: context) // You can reuse the same view code
        } dynamicIsland: { context in
             DynamicIsland { ... } // Reuse same Island code
        }
        .supplementalActivityFamilies([.small, .medium]) // <--- The specific difference
    }

so how is the code on react native gonna be?

V3RON · 2026-01-16T12:46:32Z

We would accept supplementalActivityFamilies in startLiveActivity, and based on its value we would use a different Activity on the Swift side, switching from DefaultVoltraLiveActivityAttributes (currently VoltraAttributes) to WatchVoltraLiveActivityAttributes. I’m not sure whether it’s legitimate to change the attributes type during the lifetime of an activity, but I guess we’ll find out in practice.

mrevanzak · 2026-01-16T16:29:10Z

We would accept supplementalActivityFamilies in startLiveActivity, and based on its value we would use a different Activity on the Swift side, switching from DefaultVoltraLiveActivityAttributes (currently VoltraAttributes) to WatchVoltraLiveActivityAttributes. I’m not sure whether it’s legitimate to change the attributes type during the lifetime of an activity, but I guess we’ll find out in practice.

just dont supply it into supplementalActivityFamilies object when start those?

mrevanzak · 2026-01-16T16:32:42Z

or if you mean that you dont want certain variant to be not shown on watch at all then yeah we need to adjust it

mrevanzak · 2026-01-20T09:43:24Z

any update? @V3RON

V3RON · 2026-01-22T13:12:18Z

Sorry! Focused on delivering Android as soon as possible. I'll get back to this PR in the morning 🙏

V3RON · 2026-01-26T11:34:20Z

I allowed myself to go with a refactor to enable runtime switching between Watch/CarPlay-enabled and iPhone-only Live Activities. I'm waiting for my test Watch to charge and boot so I can test it in practice.

V3RON · 2026-01-26T12:06:36Z

Okaaay. This .supplementalActivityFamilies works differently than I expected.

If you don't provide it, the Live Activity will still be displayed, but the OS will provide a fallback layout.
If you provide .small, the system will stop providing a fallback for WatchOS, CarPlay, or StandBy (small widget) and rely solely on your code. If you don’t handle it, you’ll get an empty view.
If you provide .medium, the system will stop providing a fallback for StandBy (full width) and rely solely on your code. If you don’t handle it, you’ll get an empty view.

Technically, we need four variants:

Default
With small
With medium
With both small and medium

Alternatively, we can have one variant with all families enabled and custom code to provide reasonable fallbacks via Voltra.

V3RON · 2026-01-26T12:21:37Z

I think it's reasonable to go with the "Voltra provides fallback" approach, so we can return to a single WidgetAttributes variant.

Sorry for going back and forth on this, but testing it in practice really opened my eyes 🙈
I'm going to push an update later today.

V3RON · 2026-01-26T17:12:42Z

Alright, I think it's ready for a review from your side @mrevanzak. Let me know what do you think about it.

mrevanzak · 2026-01-26T17:40:45Z

Okaaay. This .supplementalActivityFamilies works differently than I expected.

If you don't provide it, the Live Activity will still be displayed, but the OS will provide a fallback layout.

If you provide .small, the system will stop providing a fallback for WatchOS, CarPlay, or StandBy (small widget) and rely solely on your code. If you don’t handle it, you’ll get an empty view.

If you provide .medium, the system will stop providing a fallback for StandBy (full width) and rely solely on your code. If you don’t handle it, you’ll get an empty view.

Technically, we need four variants:

Default

With small

With medium

With both small and medium

Alternatively, we can have one variant with all families enabled and custom code to provide reasonable fallbacks via Voltra.

hmmm interesting. I never delved deeply into it.

mrevanzak · 2026-01-27T06:11:05Z

all good i think @V3RON

mrevanzak added 12 commits January 15, 2026 00:25

feat(types): add supplemental activity families to LiveActivityVariants

2fcfa62

feat(renderer): add supplemental family region rendering

550a48d

feat(swift): add supplemental family cases to VoltraRegion

4f92fd8

feat(swift): add iOS 18 supplementalActivityFamilies support with ada…

8cf3bd7

…ptive view

feat(plugin): add ActivityFamily types for supplemental families config

0b961ce

feat(plugin): add activity family constants and Swift mapping

9b1c236

feat(plugin): add validation for supplemental activity families

6f962ff

feat(plugin): generate supplementalActivityFamilies in widget bundle

678dce5

feat(plugin): wire up liveActivity config to iOS generation

0fc1175

fix(swift): separate @unknown default into own case in switch statement

696414e

Swift syntax requires @unknown default to be its own case, cannot combine with other patterns.

V3RON self-requested a review January 14, 2026 19:40

mrevanzak force-pushed the feat/activity-family branch from dca490f to 1ac4a0a Compare January 14, 2026 20:05

mrevanzak added 2 commits January 15, 2026 13:18

refactor: rename

3fec03b

fix: restore accidentally removed comments

66d2a18

V3RON reviewed Jan 15, 2026

View reviewed changes

mrevanzak added 3 commits January 15, 2026 16:51

refactor: wording

7cd3db9

refactor: wording

0c054cc

docs: no need to dive into technical on web docs

84e9362

Merge branch 'main' into feat/activity-family

432aa5a

Merge branch 'main' into feat/activity-family

8e5f42d

mrevanzak requested a review from V3RON January 22, 2026 04:20

refactor: support watch-variants at runtime

1b62a51

V3RON added 5 commits January 26, 2026 17:43

refactor: ignore .medium

a98423e

refactor: minor tweaks

c33538b

refactor: remove leftovers

53e8cc5

fix: events

75b984e

style: reformat

8bf8ab3

style: format

9556bca

V3RON merged commit 766f21b into callstackincubator:main Jan 27, 2026
4 of 5 checks passed

feat: add supplemental activity families support for iOS 18+ #13

feat: add supplemental activity families support for iOS 18+ #13

Conversation

mrevanzak commented Jan 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

TypeScript

Swift

Plugin

Usage

Requirements

Example

Uh oh!

vercel bot commented Jan 14, 2026

Uh oh!

mrevanzak commented Jan 14, 2026

Uh oh!

mrevanzak commented Jan 14, 2026

Uh oh!

V3RON commented Jan 14, 2026

Uh oh!

Uh oh!

V3RON Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

V3RON Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

mrevanzak Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

V3RON Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

mrevanzak Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

V3RON Jan 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mrevanzak Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

V3RON Jan 15, 2026

Choose a reason for hiding this comment

Uh oh!

V3RON commented Jan 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mrevanzak commented Jan 16, 2026

Uh oh!

V3RON commented Jan 16, 2026

Uh oh!

mrevanzak commented Jan 16, 2026

Uh oh!

mrevanzak commented Jan 16, 2026

Uh oh!

mrevanzak commented Jan 20, 2026

Uh oh!

V3RON commented Jan 22, 2026

Uh oh!

V3RON commented Jan 26, 2026

Uh oh!

V3RON commented Jan 26, 2026

Uh oh!

V3RON commented Jan 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

V3RON commented Jan 26, 2026

Uh oh!

mrevanzak commented Jan 26, 2026

Uh oh!

mrevanzak commented Jan 27, 2026

Uh oh!

Uh oh!

Reviewers

mrevanzak commented Jan 14, 2026 •

edited

Loading

V3RON Jan 15, 2026 •

edited

Loading

V3RON commented Jan 16, 2026 •

edited

Loading

V3RON commented Jan 26, 2026 •

edited

Loading