#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.