Widgets in Directus Mobile

Directus Mobile includes a native Latest Items home-screen widget for iOS and Android. The widget reads your Directus data and opens items directly in the app.

For admins

1) Install widget backend once per Directus server

In the app, go to Settings -> Widgets and install the widget backend. This creates/updates the required Directus collection + flow used by the widget.

What gets installed:

• Schema (collection + fields): stores each user's widget setups (for example selected collection, title, sort, limit, and slot/field configuration).
• Flow: receives the widget request, runs the configured query against Directus, and returns a small payload that the native widget can render quickly.

In short, the schema stores widget configuration, and the flow turns that configuration into live widget data.

Flow operations (high level):

1. Handshake / validation
   • validates version/support and that the widget request is structurally valid.
2. Resolve widget config
   • reads the widget config record and extracts collection, sort, limit, fields, and slot config.
3. Read context metadata
   • reads users/roles/policies/permissions/relations/fields so returned values respect Directus access rules and allowed paths.
4. Read collection data
   • queries the target collection using the widget setup (with limit/sort/fields).
5. Filter + map for widget payload
   • formats rows into widget slot values and strips disallowed/empty values.
6. Finalize response
   • adds metadata like favicon (from directus_settings) and returns a compact JSON payload for native rendering.

2) Keep Directus permissions as source of truth

Widgets do not bypass Directus auth. Each widget request uses the user session that configured or opened the widget item link.

That means:

• Role permissions, field permissions, and item filters still apply.
• If a user cannot read a collection/item in Directus, the widget cannot read it either.
• Data visibility is exactly aligned with your Directus access model.

3) Configure and support users

Users can create their own widget setups (collection, sort, limit, slots). You can guide users by:

• Ensuring their role can access the widget config collection.
• Ensuring the selected collections/fields are readable for their role.
• Keeping flow/webhook setup installed and healthy.

For end users

1) Create a setup in the app

Open Settings → Widgets and add a widget setup for each home-screen configuration you want (for example “Production / Articles” vs “Staging / Tasks”). Each setup stores:

• Which Directus collection to read (and which saved server/session the app should use for that setup).
• How items are loaded: optional title shown in the widget header, sort (Directus-style field list, e.g. -date_updated), and limit (max rows).
• Which fields are requested from Directus for that setup. The editor follows the same idea as the in-app collection table: pick the fields you need so values exist for the widget without fetching the whole collection.

Slots: where each field appears in a row

The Latest Items widget lays out each row from slots. Each slot is either tied to a field from your collection (you tap the slot and choose a field path) or left empty where that is allowed.

Slot	Role
Left	Optional narrow column (e.g. status, label, short code). If you clear the field, this column is hidden.
Title	Main line for the row—usually the item’s primary title (or similar).
Subtitle	Second line under the title for extra context (e.g. summary, date text).
Right	Optional narrow column on the other side (e.g. time, count, small meta). If you clear the field, this column is hidden.

So: title and subtitle define the main text block; left and right are optional side columns for short values.

Slot options (left and right only)

Only the left and right slots have extra layout options (the title row is shared: the main title uses the space between left and right).

• Width behaviour
  • Fit content — the side column only takes the space its text needs (good for short labels).
  • Fixed share (%) — the column uses about that percentage of the row width (0–100), so you can balance left/right vs the title when you have longer side text.

When behaviour is Fixed share, set Width (%) to the share you want; that control is hidden when behaviour is Fit content.

After you save, keep Settings → Widgets open at least once so setups sync to the device storage the home-screen widget reads.

2) Add the widget and pick a setup

You need at least one setup saved in the app (step 1). The home-screen widget does not invent setups—it reads the same list the app syncs when you open Settings → Widgets (and when you save a setup).

iOS

1. Long-press the home screen (or an empty area) → tap + (widgets gallery).
2. Find Directus Mobile → Latest Items, pick a size, then tap Add Widget.
3. Choose which setup to use:
   • While adding: if the system shows configuration, open Setup and pick one of your setups (title/collection as shown in the app).
   • After it is on the home screen: long-press the widget → Edit Widget → Setup → select the setup you want. You can change this anytime without removing the widget.

If Setup is empty, open the main app → Settings → Widgets so setups are written to shared storage, then try again.

Android

1. Long-press the home screen → Widgets (wording varies by launcher).
2. Add Directus Mobile → Latest Items (or the latest-items widget entry).
3. Configuration opens automatically for that widget instance: tap the setup you want in the list. Each widget instance you add can use a different setup.
4. If the list is empty, finish adding the widget when you can, then open the app → Settings → Widgets to create setups; remove and re-add the widget (or use Open widget settings if the configure screen offers it) to pick a setup.

3) Tap an item to open in app

Row links include your active app session when setups are synced from the app. That lets the app open the correct item without a risky “guess which session” step.

• Open Settings → Widgets once after login (or switching session) so shared storage includes sessionId. If it’s missing, rows may be non-tappable (Android) or taps may do nothing useful (iOS).
• Cold start: the first launch after a tap may show a short loading state while the app restores the session and applies the deep link.

When you tap a row, the app opens the target item for that session.

Data safety and hosting

Your data stays on your own Directus server. Directus Mobile does not move your project data to a shared Directus Mobile backend.

In practice:

• Content is fetched from your configured Directus instance(s).
• Access control is enforced by your Directus server.
• The app mirrors your Directus security boundaries instead of replacing them.

Troubleshooting

• Widget shows no setups: open app -> Settings -> Widgets and sync setups.
• Widget shows empty data: verify role/collection permissions in Directus.
• Tap opens login, or nothing happens on tap: open Settings → Widgets while logged in so setups sync with the current session id; try again. Push/other directus:// links without ?sessionId= are ignored for safety—prefer widget row taps or links that include the session query.
• Works in Simulator but not on a real iPhone (blank / endless loading): confirm the App Group is created in the Apple Developer portal and enabled for both the main app and the Latest Items widget extension; refresh provisioning / reinstall. HTTPS alone does not fix a missing or mismatched group — the widget may never read the shared config list.
• After changing widget setups, home screen still looks stale: open the app once so it can rewrite the App Group data and request a widget timeline reload.