#Developing Live Activities

Voltra provides APIs that make building and testing Live Activities easier during development.

#Supported variants

Live Activities in iOS can appear in different contexts, and Voltra supports defining UI variants for each of these contexts. For detailed information about Live Activity design guidelines, see the Apple Human Interface Guidelines.

#Lock Screen

The lockScreen variant defines how your Live Activity appears on the lock screen. It can be either a ReactNode directly, or an object with content and optional styling:

const variants = {
  lockScreen: (
    <Voltra.VStack>
      <Voltra.Text>Your content here</Voltra.Text>
    </Voltra.VStack>
  ),
}

To customize the system Lock Screen chrome, pass an object with content and activityBackgroundTint:

const variants = {
  lockScreen: {
    activityBackgroundTint: '#101828',
    content: (
      <Voltra.VStack>
        <Voltra.Text>Your content here</Voltra.Text>
      </Voltra.VStack>
    ),
  },
}

activityBackgroundTint is applied via SwiftUI's activityBackgroundTint(...) modifier on iOS. Voltra currently accepts the same color formats handled by the native iOS parser:

• Hex colors such as #RGB, #RGBA, #RRGGBB, and #RRGGBBAA
• rgb(...) and rgba(...)
• hsl(...) and hsla(...)
• Named colors: red, orange, yellow, green, mint, teal, cyan, blue, indigo, purple, pink, brown, white, gray, black, clear, transparent, primary, secondary

Use clear or transparent to make the Live Activity background transparent.

If the string cannot be parsed as one of those formats, iOS ignores the tint.

#Dynamic Island

The island variant defines how your Live Activity appears in the Dynamic Island (available on iPhone 14 Pro and later). The Dynamic Island has three display states:

• Minimal: A compact pill-shaped view that appears when the activity is in the background
• Compact: A slightly larger view with leading and trailing regions
• Expanded: A full-width view with center, leading, trailing, and bottom regions

const variants = {
  island: {
    keylineTint: '#10B981', // Optional tint color for the Dynamic Island keyline
    minimal: <Voltra.Symbol name="checkmark.circle.fill" tintColor="#10B981" />,
    compact: {
      leading: <Voltra.Text>Order</Voltra.Text>,
      trailing: <Voltra.Text>Confirmed</Voltra.Text>,
    },
    expanded: {
      center: <Voltra.Text style={{ fontSize: 16, fontWeight: '600' }}>Order Confirmed</Voltra.Text>,
      leading: <Voltra.Symbol name="checkmark.circle.fill" />,
      trailing: <Voltra.Text>ETA: 15 min</Voltra.Text>,
      bottom: <Voltra.Text style={{ fontSize: 12 }}>Your order is being prepared</Voltra.Text>,
    },
  },
}

keylineTint uses the same iOS color parser and accepted formats as activityBackgroundTint.

#Supplemental Activity Families (iOS 18+, watchOS 11+)

The supplementalActivityFamilies variant defines how your Live Activity appears on Apple Watch Smart Stack and CarPlay displays. This variant is optional and works seamlessly with your existing lock screen and Dynamic Island variants.

const variants = {
  lockScreen: (
    <Voltra.VStack>
      {/* iPhone lock screen content */}
    </Voltra.VStack>
  ),
  island: {
    /* Dynamic Island variants for iPhone */
  },
  supplementalActivityFamilies: {
    small: (
      <Voltra.HStack style={{ padding: 12, gap: 8 }}>
        <Voltra.Text style={{ fontSize: 18, fontWeight: '700' }}>12 min</Voltra.Text>
        <Voltra.Text style={{ fontSize: 14, color: '#9CA3AF' }}>ETA</Voltra.Text>
      </Voltra.HStack>
    ),
  },
}

If supplementalActivityFamilies.small is not provided, Voltra will automatically construct it from your Dynamic Island compact variant by combining the leading and trailing content in an HStack.

#Limitations

#Animations and Live Updates

There are specific constraints on how content can animate or update:

• Continuous Animations: Custom continuous animations, such as rotating icons or elements moving along a path, are not supported.
• Smooth Updates: Per-second "live" updates are only supported by specific components designed for this purpose:
  • Timer: For countdowns and stopwatches.
  • LinearProgressView: When used with timerInterval.
• Styling Trade-offs: To enable smooth, system-driven animations (like a progress bar filling up in real-time), certain components may ignore custom styling properties (e.g., custom heights or thumb components) and fallback to standard system appearances.

All other components only update their visual state when a new activity state is pushed from your application.

#useLiveActivity

For React development, Voltra provides the useLiveActivity hook for integration with the component lifecycle and automatic updates during development.

import { useLiveActivity } from 'voltra/client'
import { Voltra } from 'voltra'

function OrderLiveActivity({ orderId, status }) {
  const variants = {
    lockScreen: (
      <Voltra.VStack style={{ padding: 16, borderRadius: 18, backgroundColor: '#101828' }}>
        <Voltra.Text style={{ color: '#F8FAFC', fontSize: 18, fontWeight: '600' }}>
          {status === 'confirmed' ? 'Order Confirmed' : 'Order Ready'}
        </Voltra.Text>
        <Voltra.Text style={{ color: '#94A3B8', fontSize: 12, marginTop: 8 }}>
          {status === 'confirmed' ? 'Your order is being prepared' : 'Your order is ready for pickup'}
        </Voltra.Text>
        {status === 'ready' && (
          <Voltra.Button onPress="pickup-order" style={{ marginTop: 12 }}>
            I'm Here
          </Voltra.Button>
        )}
      </Voltra.VStack>
    ),
  }

  const { start, update, end, isActive } = useLiveActivity(variants, {
    activityName: `order-${orderId}`,
    autoStart: true, // Automatically start when component mounts
    autoUpdate: true, // Automatically update when variants change
    deepLinkUrl: `myapp://order/${orderId}`,
  })

  // Manual control if needed
  const handleCancelOrder = async () => {
    await end()
  }

  return (
    <View>
      <Text>Live Activity: {isActive ? 'Active' : 'Inactive'}</Text>
      <Button onPress={handleCancelOrder} title="Cancel Order" />
    </View>
  )
}

#VoltraView Component

For testing and development, Voltra provides a VoltraView component that renders Voltra JSX components directly in your React Native app. This is useful for:

• Testing component layouts before deploying to Live Activities
• Handling user interactions in development
• Previewing how your Live Activity will look

import { VoltraView } from 'voltra/client'
import { Voltra } from 'voltra'

function MyComponent() {
  const handleInteraction = (event: VoltraInteractionEvent) => {
    console.log('User interacted with:', event.identifier)
    console.log('Payload:', event.payload)
  }

  return (
    <VoltraView
      id="my-test-view"
      onInteraction={handleInteraction}
      style={{ height: 200, borderRadius: 12, overflow: 'hidden' }}
    >
      <Voltra.VStack style={{ padding: 16, backgroundColor: '#101828' }}>
        <Voltra.Text style={{ color: '#F8FAFC', fontSize: 18, fontWeight: '600' }}>Test Live Activity</Voltra.Text>
        <Voltra.Text style={{ color: '#94A3B8', fontSize: 12, marginTop: 8 }}>This is how it will look</Voltra.Text>
        <Voltra.Button id="test-button" style={{ marginTop: 12 }}>
          <Voltra.Text>Test Button</Voltra.Text>
        </Voltra.Button>
      </Voltra.VStack>
    </VoltraView>
  )
}

Props:

• id: Unique identifier for the view (used for event filtering)
• children: Voltra JSX components to render
• style: React Native style for the container
• onInteraction: Callback for user interactions with buttons/toggles

**Hook Options:**

- `activityName`: Name of the Live Activity
- `autoStart`: Automatically start when component mounts
- `autoUpdate`: Automatically update when variants change
- `deepLinkUrl`: URL to open when Live Activity is tapped

**Hook Returns:**

- `start()`: Start the Live Activity
- `update()`: Update the Live Activity
- `end()`: Stop the Live Activity
- `isActive`: Boolean indicating if the Live Activity is currently active