Building Widgets

Widgets are the core of NativeSuite — native UI elements on your users' home screens, powered by your API data. This guide covers picking templates, mapping data, and configuring styles.

Creating a Widget

Widgets belong to a release. To create one:

1. Navigate to your app → Releases → select a release (must be in Draft status)
2. Click Add Widget
3. Choose a template
4. Configure data source, field mapping, and style

Choosing a Template

NativeSuite provides seven built-in templates. Pick the one that best fits your data.

Stat

Best for: single metrics with optional trend indicators.

Slots:

• label — What the metric is (e.g., "Monthly Revenue")
• value — The main number or text
• change — Optional change indicator (e.g., "+12.4%")

Example: Monthly revenue widget showing "$48,290" with a "+12.4%" trend.

Card

Best for: alerts, updates, or status messages.

Slots:

• tag — Optional category label (e.g., "Critical", "New")
• title — The main heading
• body — Supporting text

Example: "Order #4821 shipped — Your package is on the way to Berlin, DE"

List

Best for: ordered items with status.

Slots:

• title — List heading
• items — Array of items, each with:
  • text — Item content
  • status — Optional status indicator (done, pending, etc.)

Example: Today's tasks with completion checkmarks.

Table

Best for: structured data in rows and columns.

Slots:

• title — Table heading
• columns — Column headers
• rows — Array of row data

Example: Service health dashboard with service name, region, and status.

Chart

Best for: trends and comparisons.

Slots:

• title — Chart heading
• value — Summary value
• bars — Array of data points, each with:
  • label — X-axis label
  • value — Bar height

Example: Weekly signups bar chart.

Image

Best for: visual content from your API.

Slots:

• url — Image URL
• caption — Optional text below the image

Text

Best for: formatted text blocks, digests, summaries.

Slots:

• eyebrow — Small text above the heading
• heading — Main heading
• body — Body text

Mapping Data Fields

After choosing a template and data source, you map your API response fields to the template's slots.

Static vs. Dynamic Values

• Static — A fixed string you type in (e.g., label: "Monthly Revenue")
• Dynamic — A field from your data source (e.g., value: mapped to revenue.total)

Using Liquid Templates

For more complex mappings, NativeSuite supports Liquid template syntax:

${{ revenue.total | divided_by: 1000.0 | round: 1 }}K

This lets you format, transform, and combine data fields before they reach the widget.

See the Liquid Templates reference for the full syntax.

Widget Sizes

Widgets support up to three sizes on the home screen:

Size	Description	Best For
Compact	Small, single-glance	Stats, simple indicators
Standard	Medium, default size	Cards, short lists
Expanded	Large, detailed	Full lists, tables, charts

Not all templates support all sizes. Configure which sizes your widget supports when creating it.

Visibility Conditions

You can conditionally show or hide a widget based on data field values. For example:

• Only show an "Alerts" widget when alert_count > 0
• Hide a widget when status == "inactive"

This is configured in the widget settings under visibility conditions.

Styling

Each template has style options specific to its layout. Common options include:

• Color scheme — Accent colors for the widget
• Layout variant — Different visual arrangements within the same template

Best Practices

• Keep it glanceable — Widgets are meant to be read in seconds. Don't overload them with data
• Use meaningful labels — "Monthly Revenue" is better than "Value 1"
• Pick the right size — Use compact for quick numbers, expanded for detailed views
• Test on real devices — Widget rendering varies by OS and screen size
• Consider refresh rates — Widget data refreshes periodically, not in real-time. Design for slight staleness