Developing Android Widgets

Voltra allows you to build Android Home Screen widgets using JSX and Jetpack Compose Glance primitives.

Glance Primitives

On Android, you use VoltraAndroid components which map to Glance primitives:

• Column: Vertical layout
• Row: Horizontal layout
• Box: Stacked layout
• Spacer: Flexible spacing
• Text: Displaying text
• Image: Displaying images
• Scaffold: Top-level container

Example Widget

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

const WeatherWidget = ({ temperature, condition }) => (
  <VoltraAndroid.Box
    style={{
      padding: 16,
      backgroundColor: '#f0f0f0',
      borderRadius: 12,
      width: '100%',
      height: '100%'
    }}
  >
    <VoltraAndroid.Column>
      <VoltraAndroid.Text style={{ fontSize: 24, fontWeight: 'bold' }}>
        {temperature}°C
      </VoltraAndroid.Text>
      <VoltraAndroid.Text style={{ color: '#666' }}>
        {condition}
      </VoltraAndroid.Text>
    </VoltraAndroid.Column>
  </VoltraAndroid.Box>
)

Update API

To update a widget’s content, use the updateAndroidWidget function from @use-voltra/android-client:

import { updateAndroidWidget } from '@use-voltra/android-client'

await updateAndroidWidget('weather_widget', <WeatherWidget temperature={22} condition="Sunny" />)

updateAndroidWidget only updates payload-driven widgets like this one. Calling it on a Dynamic Widget (see Dynamic Widgets) rejects with VOLTRA_WIDGET_KIND_MISMATCH.

Layout Constraints

Unlike standard React Native or iOS Stacks, Android Glance layouts are more restrictive:

• Width/Height: Use fixed numbers (dp), "100%" to fill available space, or "auto" to wrap content.
• Modifiers: Most styling is handled via the style prop, which maps to Glance Modifiers. See Styling for full details.
• Alignment: Use verticalAlignment and horizontalAlignment props on Column and Row.

Advanced Features

• Querying Active Widgets: Detect active widget instances and their sizes.
• Testing and Previews: Preview layouts within your app.
• Widget Picker Previews: Configure how your widget appears in the Android widget picker.
• Image Preloading: Cache remote images for use in widgets.
• Widget Pre-rendering: Provide initial state for widgets before the app first runs.