Native modifiers

Native modifiers apply Jetpack Glance modifiers that style does not cover, such as semantics, appWidgetBackground and day/night backgrounds, to any Voltra Android component.

Add a modifier

Pass a list of modifiers from VoltraAndroid.modifiers to the modifiers prop:

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

const { appWidgetBackground, background, semantics, visibility } = VoltraAndroid.modifiers

export default function PortfolioWidget({ balance, stale }: { balance: string; stale: boolean }) {
  return (
    <VoltraAndroid.Column
      style={{ width: '100%', height: '100%', padding: 12 }}
      modifiers={[
        appWidgetBackground(),
        background(AndroidDynamicColors.surface),
        semantics({ contentDescription: `Portfolio balance ${balance}` }),
      ]}
    >
      <VoltraAndroid.Text style={{ fontSize: 24 }}>{balance}</VoltraAndroid.Text>
      <VoltraAndroid.Text modifiers={[visibility(stale ? 'visible' : 'gone')]}>Updating…</VoltraAndroid.Text>
    </VoltraAndroid.Column>
  )
}

VoltraAndroid components only accept modifiers from VoltraAndroid.modifiers. Passing a modifier from Voltra.modifiers, or a plain object, is a TypeScript error.

How modifiers combine with `style`

Glance applies modifiers after style, and it does not care about their order:

Where a modifier and a style property set the same thing, such as a width or a background, the modifier wins. There are three exceptions:
- style.flex on a child of a Row or Column replaces the child’s width, height, size, fillMax… and wrapContent… modifiers along the row or column.
- A Scaffold always fills the widget and draws its own background and rounded corners, so size modifiers, background and cornerRadius on the Scaffold itself have no effect. Use its backgroundColor prop instead.
- FilledButton, OutlineButton, CircleIconButton and SquareIconButton draw their own background and rounded corners, so background and cornerRadius on them have no effect. Use their color props instead.
Chart, ArcProgressIndicator and Text with renderAsBitmap take their size from the size modifiers. wrapContentWidth, wrapContentHeight and wrapContentSize on them keep their default size.
Padding adds up. style={{ padding: 8 }} with modifiers={[padding(8)]} gives 16 dp.
Using the same modifier twice keeps the last one, except for padding and absolutePadding, which add up.

Available modifiers

Modifier	What it does
`padding(dp \| { all?, horizontal?, vertical?, start?, top?, end?, bottom? })`	Adds padding that follows the layout direction.
`absolutePadding(dp \| { all?, horizontal?, vertical?, left?, top?, right?, bottom? })`	Adds padding that ignores the layout direction.
`width(dp)`, `height(dp)`, `size(dp \| { width, height })`	Sets a fixed size.
`fillMaxWidth()`, `fillMaxHeight()`, `fillMaxSize()`	Fills the available space.
`wrapContentWidth()`, `wrapContentHeight()`, `wrapContentSize()`	Sizes to the content.
`background(color \| { day, night })`	Fills the background with a color, an `AndroidDynamicColors` token, or separate light and dark colors.
`cornerRadius(dp)`	Rounds the corners. Android 12+.
`visibility('visible' \| 'invisible' \| 'gone')`	Shows the component, hides it but keeps its space, or removes it from layout.
`semantics({ contentDescription?, testTag? })`	Sets the text read by accessibility services. `testTag` is only visible to Glance’s own test APIs, not to UI tests of the widget on a device. At least one of the two is required.
`appWidgetBackground()`	Marks the widget background so the launcher can animate it when the widget opens your app. Use it once, on the outermost component. If several components set it, only one keeps it. Inside a widget with a `Scaffold`, it is skipped because the `Scaffold` marks its own background. Android 12+.

For light and dark colors, background({ day, night }) takes two static color strings; AndroidDynamicColors tokens are a type error there. To follow the device’s Material You theme instead, pass an AndroidDynamicColors token. See Dynamic Colors.

Native modifiers do not handle taps. To open your app from a component, use its deepLinkUrl prop.

Troubleshooting

Corners are not rounded. cornerRadius only works on Android 12 (API 31) and later. Older versions render square corners.

A modifier has no effect. An unknown modifier or an invalid value, such as a color string that does not parse or day and night given as AndroidDynamicColors tokens, is skipped. Run adb logcat -s VoltraModifiers to see which one and why.

The launcher does not animate the widget when it opens the app. appWidgetBackground only works on Android 12 (API 31) and later. Older versions open the app without the animation.

The padding is larger than expected. Glance adds padding modifiers to style.padding. Remove one of them.