# Voltra

> Build Live Activities with JSX in React Native.

## Getting Started

- [Introduction](/getting-started/introduction.md): Voltra is a library that brings new "platforms" to React Native. Up until now, creating features like iOS Live Activities, Dynamic Island layouts, or Android Home Screen Widgets required writing native code in Swift or Kotlin. Voltra changes this by providing a JavaScript-based API and JSX components that get automatically converted to native primitives (SwiftUI on iOS, Jetpack Compose Glance on Android).

## iOS

- [Introduction](/ios/introduction.md): Adding live activities to your iOS app has traditionally been a time-consuming and complex process. JavaScript developers need to learn Xcode, master SwiftUI, understand how to start live activities, and figure out how to manage them throughout their lifecycle. This creates barriers between your app development and these dynamic features.

## Android

- [Android Introduction](/android/introduction.md): Voltra brings the power of JSX-based UI to Android Home Screen widgets. Using Jetpack Compose Glance under the hood, Voltra allows you to define Android widgets using a set of primitives that map directly to Glance components.

## Others

- [Plugin Configuration (Android)](/android/api/plugin-configuration.md): The Voltra Expo config plugin accepts Android-specific configuration options in your app.json or app.config.js:
- [Charts (Android)](/android/charts.md): Use charts in Android widgets to show trends, comparisons, progress, or composition at a glance. You can mix bars, lines, areas, points, rules, and sectors in a single chart.
- [Interactive Controls (Android)](/android/components/interactive.md): User interface controls that respond to user interaction on Android widgets. Button Standard button component. On Android, all buttons always open the application when clicked. You can provide a deepLinkUrl to open a specific screen. Parameters: enabled (boolean, optional): Whether the button is enabled.deepLinkUrl (string, optional): URL to open when the button is clicked. If not provided, the app will open to its main activity. Voltra also provides specialized button variants: FilledButton text (string): Button label.enabled (boolean, optional).deepLinkUrl (string, optional).icon (object, optional): { assetName: string }.backgroundColor (string, optional).contentColor (string, optional).maxLines (number, optional). OutlineButton text (string): Button label.enabled (boolean, optional).deepLinkUrl (string, optional).icon (object, optional): { assetName: string }.contentColor (string, optional).maxLines (number, optional). CircleIconButton & SquareIconButton enabled (boolean, optional).deepLinkUrl (string, optional).icon (object, optional): { assetName: string, base64: string }.contentDescription (string, optional).backgroundColor (string, optional).contentColor (string, optional). Clickable Components Most components support being clickable by setting the pressable prop (short name prs in raw elements) in their props. Parameters: pressable (boolean): Set to true to make the component respond to clicks.deepLinkUrl (string, optional): URL to open when clicked. Switch A toggle switch component. On Android, toggles always open the application when clicked. Parameters: id (string): Unique identifier for interaction events.checked (boolean, optional): Current state of the switch.deepLinkUrl (string, optional): URL to open when clicked.text (string, optional): Label displayed next to the switch.thumbCheckedColor (string, optional).thumbUncheckedColor (string, optional).trackCheckedColor (string, optional).trackUncheckedColor (string, optional).maxLines (number, optional): Maximum lines for the label. CheckBox Standard checkbox component. On Android, checkboxes always open the application when clicked. Parameters: id (string): Unique identifier for interaction events.checked (boolean, optional).deepLinkUrl (string, optional).text (string, optional).checkedColor (string, optional).uncheckedColor (string, optional).maxLines (number, optional). RadioButton Standard radio button component. On Android, radio buttons always open the application when clicked. Parameters: id (string): Unique identifier for interaction events.checked (boolean, optional).enabled (boolean, optional).deepLinkUrl (string, optional).text (string, optional).checkedColor (string, optional).uncheckedColor (string, optional).maxLines (number, optional).
- [Layout & Containers (Android)](/android/components/layout.md): Components that arrange other elements or provide structural grouping using Jetpack Compose Glance primitives. See Styling for details on layout and spacing properties. Column A vertical container that arranges its children in a column. Parameters: horizontalAlignment (string, optional): "start", "center-horizontally", "end".verticalAlignment (string, optional): "top", "center-vertically", "bottom". Row A horizontal container that arranges its children in a row. Parameters: horizontalAlignment (string, optional): "start", "center-horizontally", "end".verticalAlignment (string, optional): "top", "center-vertically", "bottom". Box A container that stacks its children on top of each other. Parameters: contentAlignment (string, optional): Combined alignment. Supports "top-start", "top-center", "top-end", "center-start", "center", "center-end", "bottom-start", "bottom-center", "bottom-end". Scaffold A top-level container that provides a standard layout structure for widgets. Parameters: backgroundColor (string, optional): Background color for the scaffold.horizontalPadding (number, optional): Horizontal padding in dp. TitleBar A component that displays a title bar with a required leading icon. Parameters: title (string): Title text to display.startIcon (object, required): { assetName: string } or { base64: string }.textColor (string, optional).iconColor (string, optional).fontFamily (string, optional): "monospace", "serif", "sans-serif", or "cursive". Spacer A component that provides fixed spacing between elements. Parameters: size (number): Size of the spacer in dp. LazyColumn A scrollable vertical list that only renders visible items. Parameters: horizontalAlignment (string, optional): "start", "center-horizontally", "end". LazyVerticalGrid A scrollable grid of items. Parameters: columns (number | "adaptive"): Number of columns or "adaptive" for an adaptive grid.minSize (number, optional): Minimum size (in dp) for items in adaptive grid mode.horizontalAlignment (string, optional): "start", "center-horizontally", "end".verticalAlignment (string, optional): "top", "center", "bottom".
- [Data Visualization & Status (Android)](/android/components/status.md): Components for displaying data and status information on Android widgets. LinearProgressIndicator A horizontal progress bar. Parameters: progress (number, optional): Current progress value (0.0 to 1.0). If omitted, the indicator will be indeterminate.color (string, optional): Color for the progress indicator.backgroundColor (string, optional): Color for the background track. CircularProgressIndicator A circular progress indicator. Parameters: color (string, optional): Color for the progress indicator.
- [Visual Elements & Typography (Android)](/android/components/visual.md): Static or decorative elements used to display content on Android widgets. See Styling for details on supported style properties. Text Displays text content. Parameters: maxLines (number, optional): Maximum number of lines to display.renderAsBitmap (boolean, optional): Renders text as a bitmap image to enable custom fonts. Requires fontFamily in the style prop. Image Displays bitmap images from the asset catalog, preloaded runtime cache, or base64 encoded data. SVGs should be rasterized through the image preloading API and referenced by assetName. Parameters: source (object, optional): Image source object.assetName (string): Reference to a pre-bundled image (drawable resource) or a preloaded image.base64 (string): Base64 encoded image data.resizeMode (string, optional): "cover", "contain", "stretch", "repeat", or "center".contentDescription (string, optional): Accessibility description for the image.contentScale (string, optional): Glance-specific scaling mode: "crop", "cover", "fit", "contain", "fill-bounds", or "stretch".alpha (number, optional): Opacity value from 0.0 to 1.0.colorFilter (string, optional): Color tint filter for the image.tintColor (string, optional): Legacy alias for colorFilter.fallback (ReactNode, optional): Custom content rendered when the image is missing. Styling the fallback: To add a background color when an image is missing, use backgroundColor in the style prop:
- [Custom Fonts](/android/development/custom-fonts.md): Android Glance only supports a handful of built-in font families (monospace, serif, sans-serif, cursive). Voltra works around this by rendering text as a bitmap with a custom Typeface loaded from assets/fonts/.
- [Developing Android Widgets](/android/development/developing-widgets.md): Voltra allows you to build Android Home Screen widgets using JSX and Jetpack Compose Glance primitives.
- [Dynamic colors](/android/development/dynamic-colors.md): Voltra supports Android dynamic colors through semantic tokens exposed from @use-voltra/android. These colors follow the current Android Material palette, so widgets can pick up wallpaper and theme changes without waiting for JavaScript to run again.
- [Dynamic Widgets](/android/development/dynamic-widgets.md): Dynamic Widgets let your widget react to the current device state on Android. Declare them in app.json with a stable id and an explicit entry, then default-export the widget from that file. Your widget can react to: env.widgetFamilyenv.colorSchemeenv.localeenv.configurationAndroidDynamicColors tokens, which resolve to the current Material You palette natively When you change app.json, run Expo Prebuild or Voltra Apply so the updated widget configuration is available on device. If you change only the widget JS, reopen the app in development and the widget updates automatically.
- [Image Preloading (Android)](/android/development/image-preloading.md): Android widgets have limitations when it comes to displaying remote images directly. The image preloading API allows you to download images to the app's cache directory, making them available to your widgets via a local FileProvider.
- [Images](/android/development/images.md): Voltra provides three different approaches for including images in your Android widgets, each with different trade-offs and use cases: Build-time asset copying: Best for static icons and assets known at build timeRuntime preloading: Best for dynamic images from remote URLsBase64 encoding: Best for small, generated images
- [Managing Android Ongoing Notifications](/android/development/managing-ongoing-notifications.md): Voltra supports Android ongoing notifications for local, app-driven status updates such as deliveries, rides, workouts, or timers. Use this API when you want to: start a persistent notification from your appupdate its content over timestop it when the task endsadd action buttons that open deep links in your app Voltra also supports remote updates if your app receives push notifications in the background and forwards the payload to the ongoing notification APIs.
- [Querying Active Widgets](/android/development/querying-active-widgets.md): On Android, you can detect every active instance of your widgets currently placed on the Home Screen. This is particularly useful for Android since each widget instance can have different dimensions and a unique widgetId.
- [Server-driven widgets](/android/development/server-driven-widgets.md): Server-driven widgets allow your Android Home Screen widgets to periodically fetch fresh content from a remote server—without the user opening the app. This is powered by WorkManager, which handles scheduling, retries, and network constraints automatically. Before you start, make sure the widget is registered in the Voltra plugin config and plan to rebuild the native app after adding or changing server-driven widget settings. Android semantic color tokens from AndroidDynamicColors work in server-rendered widgets too, so your backend can return dynamic Material roles instead of fixed hex values.
- [Styling](/android/development/styling.md): You can style Voltra components on Android using React Native-style style props. These properties are automatically converted to Jetpack Compose Glance modifiers. For Android system-aware colors, use AndroidDynamicColors from @use-voltra/android instead of snapshotting palette values in JavaScript.
- [Testing and Previews (Android)](/android/development/testing-and-previews.md): Voltra provides multiple ways to preview your Android widgets: In-App Previews - Preview layouts within your development app using VoltraWidgetPreviewWidget Picker Previews - Customize what users see in the Android widget picker when adding your widget This page covers in-app previews for development. For widget picker previews, see Plugin Configuration - Widget Picker Previews.
- [Widget Pre-rendering (Android)](/android/development/widget-pre-rendering.md): Widget pre-rendering allows you to provide a meaningful initial state for your Android widgets before they are updated by the app for the first time.
- [Android Setup](/android/setup.md): Once you have installed Voltra for Android, configure the Expo plugin and use @use-voltra/android for widget JSX.
- [Installation](/getting-started/installation.md): Voltra v2 ships as platform packages. In most apps, you install one package for JSX primitives and one package for runtime APIs per platform.
- [Migration to v2](/getting-started/migration-v2.md): Voltra v2 introduces two major architectural changes: The old Voltra umbrella package is gone. Voltra now ships as separate iOS, Android, and server packages.The native layer moved from Expo Modules to Turbo Modules. We made these changes to fix a few long-standing problems in the old package layout. The old umbrella package made it too easy for React Native code to leak into server builds, especially when people only wanted server-side rendering or pre-rendering. It also forced many apps to pull in both platform surfaces even when they only shipped iOS or only shipped Android. The Turbo Module migration also changes the native integration layer, so upgrading to v2 requires updating package installs, Expo plugin configuration, and some API usage. This guide walks through the package, import, and configuration changes you need to make when upgrading to v2.
- [Prior Art](/getting-started/prior-art.md): Voltra wouldn't be possible without the incredible work of the open-source community. This page acknowledges the libraries and projects that inspired and informed our approach to bridging JavaScript and native iOS Live Activities.
- [React Native CLI Projects](/getting-started/react-native-cli.md): Voltra fully supports React Native CLI projects through the voltra CLI. Instead of relying on Expo config plugins, voltra apply updates the native project for you: it modifies the files Voltra needs, generates new Voltra-owned files, and cleans up outdated generated files from previous runs.
- [Configuration](/ios/api/configuration.md): Voltra provides several configuration options to control Live Activity behavior, lifecycle, and appearance. These options can be used when starting, updating, or stopping Live Activities. For Expo plugin configuration options (like groupIdentifier, enablePushNotifications, deploymentTarget, and widgets), see the Plugin Configuration documentation.
- [Plugin configuration](/ios/api/plugin-configuration.md): The Voltra Expo config plugin accepts several configuration options in your app.json or app.config.js:
- [Charts (iOS)](/ios/charts.md): Use charts in Live Activities and widgets to show trends, comparisons, progress, or composition at a glance. You can mix bars, lines, areas, points, rules, and sectors in a single chart.
- [Interactive Controls (iOS)](/ios/components/interactive.md): User interface controls that respond to user interaction in Live Activities.
- [Layout & Containers (iOS)](/ios/components/layout.md): Components that arrange other elements or provide structural grouping.
- [Components Overview (iOS)](/ios/components/overview.md): Voltra provides SwiftUI primitives with JSX bindings, allowing developers to create rich, interactive Live Activities using React/JSX syntax. These components connect web development workflows with native iOS Live Activity rendering.
- [Data Visualization & Status (iOS)](/ios/components/status.md): Components specifically designed to show dynamic values or states over time in Live Activities and Widgets. LinearProgressView A horizontal progress bar that displays determinate progress or timer-based progress. Limitations When using timerInterval for smooth animations, custom styling properties such as height, trackColor, cornerRadius, and the thumb component are ignored. The component will use the default system appearance in this mode. CircularProgressView A circular progress indicator that displays determinate progress or timer-based progress. Limitations While timerInterval is supported, the progress ring will not animate continuously. It only updates its visual state when the component state is refreshed. For a smooth, live-animating progress bar, use LinearProgressView. Gauge A gauge indicator for progress visualization (iOS 16+). Timer A flexible component for displaying live-updating time intervals. Crucial for Live Activities, it uses native SwiftUI text interpolation to ensure the time updates automatically on the lock screen and in the Dynamic Island without requiring background updates from React Native. Modes: Timer Mode: For fixed intervals (countdowns or counting up to a target). Requires endAtMs or durationMs.Stopwatch Mode: For open-ended intervals counting up from a starting point. Requires startAtMs and direction="up", but both endAtMs and durationMs must be omitted. Parameters: startAtMs (number, optional): Start time in milliseconds since epoch.endAtMs (number, optional): End time in milliseconds since epoch.durationMs (number, optional): Duration in milliseconds. Used if endAtMs is omitted.direction (string, optional): Count direction. Can be 'up' or 'down'. Defaults to 'down'.textStyle (string, optional): Formatting style.'timer': Standard clock format (e.g., 05:00).'relative': Relative format (e.g., 5m).showHours (boolean, optional): Whether to show hours (e.g., 1:30:00 vs 90:00). Defaults to false.textTemplates (string, optional): JSON-encoded object with running and completed templates. Use {time} as a placeholder. Examples:
- [Visual Elements & Typography (iOS)](/ios/components/visual.md): Static or decorative elements used to display content. Text Displays text content. Parameters: numberOfLines (number, optional): Maximum number of lines to display Label A semantic label that can display both an icon and title text. Parameters: title (string, optional): Text content for the labelsystemImage (string, optional): SF Symbol name for the label icon Image Displays bitmap images from the asset catalog or base64 encoded data. Parameters: source (object, optional): Image source object (assetName or base64)resizeMode (string, optional): "cover", "contain", "stretch", "repeat", or "center"fallback (ReactNode, optional): Custom content rendered when the image is missing Styling the fallback: To add a background color when an image is missing, use backgroundColor in the style prop: Symbol Displays SF Symbols (system icons) with configuration options. Divider A visual divider component. LinearGradient A linear gradient background that can contain children. Mask Masks content using any Voltra element as the mask shape.
- [Configurable Widgets](/ios/development/configurable-widgets.md): Configurable widgets let users edit widget parameters in the native iOS Edit Widget sheet. Use them when a Dynamic Widget needs a few user-editable knobs, such as a label, unit, theme, or source. It requires iOS 17+, because Voltra wires it through AppIntentConfiguration.
- [Developing Live Activities](/ios/development/developing-live-activities.md): Voltra provides APIs that make building and testing Live Activities easier during development.
- [Developing Widgets](/ios/development/developing-widgets.md): Voltra provides APIs that make building and testing Home Screen widgets easier during development.
- [Dynamic Widgets](/ios/development/dynamic-widgets.md): Dynamic Widgets let your widget react to the current device state on iOS. Declare them in app.json with a stable id and an explicit entry, then default-export the widget from that file. That means your widget can react to: env.widgetFamilyenv.colorSchemeenv.localeenv.widgetRenderingModeenv.showsWidgetContainerBackgroundenv.configuration when you also add widget parameters When you change app.json, run Expo Prebuild or Voltra Apply so the updated widget configuration is available on device. If you change only the widget JS, reopen the app in development and the widget updates automatically.
- [Events](/ios/development/events.md): Voltra emits several types of events that allow your app to respond to changes in Live Activities and user interactions.
- [Flexbox Layout](/ios/development/flexbox-layout.md): Voltra supports React Native-style flexbox layout through the Voltra.View component.
- [Image Preloading](/ios/development/image-preloading.md): This page provides detailed API documentation for Voltra's image preloading system. For an overview of all image handling approaches in Live Activities, see the Images documentation. Live Activities have strict size limits (4KB per update), which makes displaying remote images challenging. The image preloading API downloads images to shared App Group storage, making them available to both your app and Live Activities.
- [Images](/ios/development/images.md): Live Activities have strict size limits (4KB per update), making image handling a critical optimization area. Voltra provides three different approaches for including images in your Live Activities, each with different trade-offs and use cases: Base64 encoding: Best for small, static images (< 1KB)Build-time asset copying: Best for medium-sized images that are known at build timeRuntime preloading: Best for dynamic images from remote URLs or inline SVG data
- [Interactions](/ios/development/interactions.md): Voltra components leverage Apple's ActivityKit to provide interactive Live Activities.
- [Managing Live Activities locally](/ios/development/managing-live-activities-locally.md): Live Activities are dynamic interfaces that display real-time information on iOS devices. Voltra provides a comprehensive set of APIs for managing the complete lifecycle of Live Activities directly from your React Native app, without requiring server-side infrastructure.
- [Performance](/ios/development/performance.md): Voltra provides automatic optimizations to help you create efficient Live Activities, but following these best practices will ensure optimal performance and stay within ActivityKit's payload size limits.
- [Querying Active Widgets](/ios/development/querying-active-widgets.md): Voltra allows you to detect which widgets the user has currently placed on their Home Screen. This is useful for: Determining if you need to update a specific widgetShowing a list of active widgets in your app settingsOptimizing background updates by only targeting installed widgets
- [Server-driven widgets](/ios/development/server-driven-widgets.md): Server-driven widgets allow your Home Screen widgets to periodically fetch fresh content from a remote server—without the user opening the app. This is ideal for widgets that display dynamic data like weather, news, stock prices, or live scores. Before you start, make sure the widget is registered in the Voltra plugin config and plan to rebuild the native app after adding or changing server-driven widget settings.
- [Server-side updates](/ios/development/server-side-updates.md): Voltra supports server-side updates for Live Activities through Apple Push Notification Service (APNS). This allows you to update Live Activities even when your app is in the background or terminated.
- [Styling](/ios/development/styling.md): You can style Voltra components using React Native-style style props. The style prop works with a limited set of React Native properties that are automatically converted to SwiftUI modifiers under the hood.
- [Widget Pre-rendering](/ios/development/widget-pre-rendering.md): Widget pre-rendering allows you to provide meaningful initial state for widgets before they are synced when the app runs for the first time.
- [iOS Setup](/ios/setup.md): Once you have installed Voltra, configure the iOS Expo plugin and use @use-voltra/ios for JSX.