Android Widgets

weNow provides four Android home screen widget types, built with react-native-android-widget. All widgets update automatically every 30 minutes to keep weather data current.

Widget Types

Widget	Size	Content
Small	2x2	Temperature, weather icon, and city name. A glanceable temperature check with day/night gradient background.
Large	4x2	Current weather with temperature, description, feels-like, humidity, and wind speed on the left. 3-day (or 3-hour) forecast on the right.
Detailed	4x3+	Full weather dashboard: centered icon and temperature hero, description, feels-like, confidence badge, humidity, wind, temperature range, and a 2-column 6-day (or 6-hour) forecast.
Overlay	4x3	Transparent glass widget designed to sit over the wallpaper. Displays time, city, temperature, description, 5-item forecast row, and humidity/wind footer.

Forecast Modes

The Large, Detailed, and Overlay widgets support two forecast display modes:

Daily -- Shows upcoming days (e.g., Mon, Tue, Wed) with high and low temperatures for each day.
Hourly -- Shows upcoming hours (e.g., 14h, 15h, 16h) with the predicted temperature for each hour.

The forecast mode is configurable per widget through the widget configuration screen. The Small widget does not include a forecast section due to its compact 2x2 size.

Widget Configuration

When a user adds a widget to their home screen, the configuration screen appears with the following options:

Location -- Search for a city by name or choose "Use current location" to use the device's GPS coordinates. Each widget stores its own location independently.
Forecast mode -- Toggle between "Daily" and "Hourly" forecast display (available for Large, Detailed, and Overlay widgets).

Configuration is stored per widget in AsyncStorage, so each widget on the home screen can show a different city and forecast mode.

Data Flow

The widget task handler receives a lifecycle event from Android (ADDED, UPDATE, RESIZED, or DELETED).
For ADDED and UPDATE events, the handler reads the per-widget location from AsyncStorage.
It fetches weather data from the backend's POST /api/weather/widget endpoint, which has a dedicated rate limit of 100 requests per day (separate from the main app's 5 requests per day).
The response data is processed and passed to the appropriate widget component for rendering.
The widget component returns a JSX tree that is serialized into an Android RemoteViews bitmap for display on the home screen.

Technical Details

Widget rendering in react-native-android-widget works fundamentally differently from normal React Native components:

JSX tree serialization -- Widget components produce a JSX tree that is serialized to Android RemoteViews bitmaps. This is not React's renderer -- there is no virtual DOM, no reconciliation, and no component lifecycle.
Primitive components only -- Only a limited set of primitives can appear in widget JSX: FlexWidget (flexbox container), TextWidget (text display), SvgWidget (inline SVG), ImageWidget, IconWidget, ListWidget (scrollable list, max 2 per widget), and OverlapWidget (z-stacked children). Standard React Native components like View and Text are not supported.
No hooks or state -- Because widgets are serialized rather than rendered, React hooks (useState, useEffect, etc.), Context, and Fragments cannot be used inside widget components. All data must be passed in as props.
Procedural SVG weather icons -- Weather icons are generated as inline SVG markup with no network requests and no image assets. Icons are day/night aware, switching between sun and moon variants based on the current time.

Overlay Widget Specifics

The Overlay widget is designed to float transparently over the user's wallpaper, requiring special visual treatment:

Semi-transparent background -- Uses rgba(0, 0, 0, 0.50) to provide a dark glass effect that lets the wallpaper show through while maintaining text readability.
Text shadows -- All text elements have strong shadows (radius 8, color #000000) to ensure readability against any wallpaper, light or dark.
Tappable refresh -- The weather icon has a clickAction that triggers a data refresh, allowing users to update their widget without opening the app.

Testing Limitations

Widgets cannot be tested in Expo Go because they depend on native Android widget infrastructure. To test widgets during development, you must create a native EAS build:

eas build --profile preview --platform android

Install the resulting APK on a physical device or emulator, then add the widget from the Android home screen's widget picker.