#Styling

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.

#Supported Properties

The following React Native style properties are supported on Android:

#Layout

• width, height - Fixed dimensions (number values in dp) or "100%" to fill available space.
• flex, flexGrow - Flex weight. When > 0, the component will take up a proportional amount of space in its parent container (maps to .defaultWeight() in Glance).
• padding - Uniform padding on all edges.
• paddingTop, paddingBottom, paddingLeft, paddingRight - Individual edge padding.
• paddingHorizontal, paddingVertical - Horizontal and vertical padding.
• visibility - Controls component visibility ("visible", "hidden", or "invisible").

#Visual Style

• backgroundColor - Background color (hex strings, color names, or AndroidDynamicColors.* tokens).
• backgroundImage - CSS gradient background. Supports linear-gradient(...), radial-gradient(...), and conic-gradient(...).
• borderRadius - Corner radius value. Note: Requires Android 12+ (API 31). On older versions, this property is ignored.

#Text

• fontSize - Font size in sp.
• fontWeight - Supports "normal" and "bold".
• fontFamily - Font family name. Built-in values: "monospace", "serif", "sans-serif", "cursive". For custom fonts, see Custom Fonts.
• color - Text color (literal colors or AndroidDynamicColors.*).
• textDecorationLine - Supports "underline" and "line-through".
• textAlign - Alignment of text within the component ("left", "center", "right").
• numberOfLines - Limits the number of lines displayed.

#Image Specific

In addition to general styles, Image components support:

• resizeMode - "cover", "contain", "stretch", "repeat", or "center".
• contentScale - "crop", "cover", "fit", "contain", "fill-bounds", or "stretch".
• alpha - Opacity of the image (0.0 to 1.0).
• colorFilter - Applies a color filter to the image.

#Dynamic colors

Android widgets can use semantic Material color roles that resolve through native GlanceTheme.colors.* values during rendering.

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

const element = (
  <VoltraAndroid.Box
    style={{
      padding: 16,
      backgroundColor: AndroidDynamicColors.widgetBackground,
    }}
  >
    <VoltraAndroid.Text
      style={{
        color: AndroidDynamicColors.onSurface,
        fontSize: 18,
        fontWeight: 'bold',
      }}
    >
      Android Widget Text
    </VoltraAndroid.Text>
  </VoltraAndroid.Box>
)

This is the preferred approach when you want widgets to follow Android's dynamic palette even when the app is not running. See Dynamic Colors for the full role list and server-rendering behavior.

#Gradient Backgrounds

Android widgets support gradient backgrounds through the camel-case style.backgroundImage property.

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

const element = (
  <VoltraAndroid.Box
    style={{
      width: '100%',
      height: '100%',
      padding: 16,
      borderRadius: 16,
      backgroundColor: '#0F172A',
      backgroundImage: 'linear-gradient(to right, #22D3EE 0%, #6366F1 100%)',
    }}
  >
    <VoltraAndroid.Text
      style={{
        color: '#F8FAFC',
        fontSize: 18,
        fontWeight: 'bold',
      }}
    >
      Gradient Widget
    </VoltraAndroid.Text>
  </VoltraAndroid.Box>
)

Supported gradient functions are linear-gradient(...), radial-gradient(...), and conic-gradient(...). Repeating gradients, malformed gradients, unsupported color tokens, and invalid stop positions are ignored. If backgroundColor is also provided, Android paints it behind transparent gradient pixels and uses it as a fallback when a gradient cannot be rendered.

Gradient stops can use Android dynamic color tokens from AndroidDynamicColors, but those colors are resolved into the generated bitmap when the widget renders or updates. Existing gradient bitmaps do not recolor until the widget is rendered again.

Use backgroundImage, not background-image. Gradient bitmaps are generated natively during widget rendering and capped before being passed to Glance, so the bitmap does not control layout size.

#Limitations

The following properties are NOT supported on Android due to Glance limitations:

• Margins: margin, marginTop, etc. are not part of Android style types. If you need margin-like outside spacing, use VoltraAndroid.Spacer between elements.
• Borders: borderWidth and borderColor are not yet implemented.
• Shadows: shadowColor, shadowOffset, shadowOpacity, and shadowRadius are not supported.
• Positioning: Absolute positioning (top, left, zIndex) is not supported. Use stack alignments and spacers.
• Transforms: transform (rotate, scale, etc.) is not supported.
• Opacity: The general style.opacity property is not supported (except for the alpha prop on Image).
• Dimensions: minWidth, maxWidth, minHeight, maxHeight, and aspectRatio are not supported.
• Text Effects: letterSpacing, fontVariant, and custom lineHeight are not supported.

#Example

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

const element = (
  <VoltraAndroid.Column
    style={{
      padding: 16,
      backgroundColor: '#101828',
    }}
  >
    <VoltraAndroid.Text
      style={{
        color: '#F8FAFC',
        fontSize: 18,
        fontWeight: 'bold',
      }}
    >
      Android Widget Text
    </VoltraAndroid.Text>
  </VoltraAndroid.Column>
)