Voltra Documentation

Voltra is a framework that enables React Native developers to build native iOS Live Activities (including Dynamic Island experiences) and Home Screen widgets for both iOS and Android using React components. It eliminates the need to write manual Swift or Kotlin code by allowing developers to compose native interfaces using JSX.

Key capabilities include:

• Native Primitives in JSX: Use SwiftUI (iOS) and Jetpack Compose Glance (Android) primitives directly within your React code.
• Unified Workflow: Build Live Activities and widgets for both platforms using a single React-based approach.
• Push-to-update: Stream real-time updates to iOS Live Activities via push notifications from any JavaScript runtime, allowing activities to stay current without requiring user interaction with the app.
• Developer Experience: Supports hot reload and includes an Expo config plugin for automatic wiring.

Voltra allows you to define Android Home Screen widgets using JSX-based primitives that map to Jetpack Compose Glance components.

Note: Android support is currently experimental. The API is subject to change.

To build for Android, use the VoltraAndroid namespace to access platform-specific primitives like Column, Row, and Box. This ensures your UI adheres to Android's layout and styling rules, which differ from iOS's SwiftUI-based primitives.

import { VoltraAndroid } from 'voltra'

const MyWidget = () => (
  <VoltraAndroid.Column
    style={{
      padding: 16,
      backgroundColor: '#3DDC84',
      width: '100%',
      height: '100%'
    }}
    verticalAlignment="center-vertically"
    horizontalAlignment="center-horizontally"
  >
    <VoltraAndroid.Text
      style={{
        color: 'white',
        fontSize: 18,
        fontWeight: 'bold'
      }}
    >
      Android Widget
    </VoltraAndroid.Text>
    <VoltraAndroid.Text
      style={{
        color: 'white'
      }}
    >
      Powered by Voltra & Glance
    </VoltraAndroid.Text>
  </VoltraAndroid.Column>
)

Voltra allows you to build Android Home Screen widgets using JSX. It uses Jetpack Compose Glance under the hood, mapping Voltra primitives to Glance components.

Note: Android support is currently experimental. The API may change in future versions.

To build Android-specific widgets, use the @use-voltra/android package and its VoltraAndroid namespace. This ensures your UI uses the correct Jetpack Compose Glance primitives like Column, Row, and Box instead of iOS-centric stacks.

import { VoltraAndroid } from '@use-voltra/android'

const MyWidget = () => (
  <VoltraAndroid.Column
    style={{
      padding: 16,
      backgroundColor: '#3DDC84',
      width: '100%',
      height: '100%'
    }}
    verticalAlignment="center-vertically"
    horizontalAlignment="center-horizontally"
  >
    <VoltraAndroid.Text
      style={{
        color: 'white',
        fontSize: 18,
        fontWeight: 'bold'
      }}
    >
      Android Widget
    </VoltraAndroid.Text>
    <VoltraAndroid.Text
      style={{
        color: 'white'
      }}
    >
      Powered by Voltra & Glance
    </VoltraAndroid.Text>
  </VoltraAndroid.Column>
)

The @use-voltra/android-client package provides the following capabilities for Android React Native development:

• Payload-driven Home Screen widgets: Render and update widget variants with updateAndroidWidget, then reload, pin, and query widgets with reloadAndroidWidgets, getActiveWidgets, and more.
• Dynamic Widgets (experimental): Declare widgets in app.json and render them on-device using runtime props and live environment values (size, color scheme, Material You colors, locale, configuration).
• Ongoing notifications: Start and update promoted ongoing notifications with useAndroidOngoingNotification and related APIs.
• Fast Refresh: Previews integrate with React Native dev workflow via VoltraWidgetPreview and VoltraView.
• Image preloading: Download remote images for widgets with preloadImages and reloadWidgets.
• Server-driven widgets: Store credentials for background widget fetches with setWidgetServerCredentials.
• Expo config plugin: Declarative widget and notification configuration via app.json.