Skip to content

feat: configurable widgets (iOS 17+)#147

Open
V3RON wants to merge 1 commit into
mainfrom
feat/edit-widget
Open

feat: configurable widgets (iOS 17+)#147
V3RON wants to merge 1 commit into
mainfrom
feat/edit-widget

Conversation

@V3RON
Copy link
Copy Markdown
Contributor

@V3RON V3RON commented May 12, 2026

Summary

Widgets today show the same content for every user. The only way to personalise what a widget displays is to open the app and push new content via updateWidget(). This creates a frustrating gap: users who want a stock widget showing a specific ticker, or a news widget showing their preferred category, have no native way to express that preference.

Configurable widgets solve this. iOS 17 introduced AppIntentConfiguration, which surfaces a native "Edit Widget" sheet for any parameters you declare. This PR adds full support for that feature in Voltra — from plugin config through native Swift codegen to the React Native read API.

  • parameters in plugin config — declare enum, bool, int, or double parameters; Voltra generates the required AppEnum, WidgetConfigurationIntent, and AppIntentConfiguration Swift types at prebuild time
  • outdatedStatePath — pre-rendered holding state shown while the user has changed parameters but the app hasn't re-rendered yet (non-server widgets)
  • getWidgetParameters(widgetId) — new synchronous JS API (iOS-only, @use-voltra/ios-client) that reads the current parameter values from the shared App Group
  • Server-driven widgets — parameter values are automatically appended as query params on every server fetch; no app interaction needed
  • VoltraConfigurableHomeWidgetProvider — reusable generic AppIntentTimelineProvider in the Swift package; generated code is a thin shell over it
  • Placeholder fix — both VoltraHomeWidgetProvider and VoltraConfigurableHomeWidgetProvider now serve stale cached content from placeholder(in:) instead of showing a spinner
  • Example app — new Greeting Widget with name/theme/emoji parameters and a Configurable Widget testing screen
  • Docs — new "Configurable widgets" page, updated plugin configuration reference

Test plan

  • Add greeting widget to home screen; confirm it renders initial state
  • Long-press → Edit Widget; change name, theme, show emoji toggle
  • Confirm widget shows outdated state immediately after saving
  • Open app → navigate to Configurable Widget screen; confirm preview updates and widget re-renders
  • Verify getWidgetParameters('greeting') returns the values selected in the edit sheet
  • Confirm non-configurable widgets (weather, portfolio) are unaffected
  • Confirm iOS <17 builds compile (static widgets unchanged, configurable structs are @available(iOS 17.0, *))

Add support for the "Edit Widget" button on iOS, allowing users to personalise
widget content from the home screen without opening the app.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant