A column
A set of values. Stat averages it; a list shows its rows. The layout decides how to use it.
The data guide
Your data.
On your screen.
Start with one connection and one widget. We’ll help you get a real value on screen, then make it your own.
No code neededUse Google SheetsEdit your data in a spreadsheet.
For APIs & custom dataUse a JSON endpointConnect a URL that returns data.
For the current pre-release app. No connection required if you’d rather type your own text or numbers.
A quick orientation
Connect once.
Make it yours.
- Add a source
A source is the Sheet or endpoint WidgetWire reads. One source can power several widgets.
- Choose what to show
Mapping connects a widget’s content slot—like Value or Caption—to a column or one cell.
- Save and install
Preview your design in the app, save it, then add the widget through iOS.
01 / Google Sheets
From sheet to screen.
You’ll need a Google Sheet that can be read without signing in. WidgetWire reads it; it never edits your spreadsheet.
Set up your rows.
Put unique, non-empty column names in row 1 and one item per row underneath. No title rows or merged cells. Download our CSV and import it into a new Sheet using File → Import in Google Sheets on a computer.
Download example spreadsheet CSV ↓
On a phone, you can enter the small table below in the Sheets app instead. The full CSV adds Date, Status, Text and Active columns for the other recipes.
Choose link access.
In Google Sheets, open Share → General access, choose Anyone with the link and set the role to Viewer. Copy the link and save the sharing change. On iPhone, look for Manage access if General access isn’t shown.
Download/export access must also be allowed. Work or school accounts may restrict sharing. Google’s sharing help · Import help
Connect in WidgetWire.
Open Sources, tap + (or Connect if empty), choose Google Sheets, paste the Sheet URL and tap Connect. No Google sign-in or API key is needed.
Check what came through.
Open the saved source. Look under Columns and Data: Name, Value and Percent should appear, with Design and 20 in the first data row. Then make your first widget.
| Name | Value | Percent |
|---|---|---|
| Design | 20 | 0 |
| Build | 40 | 50 |
| Review | 60 | 100 |
| Launch 🚀 | 80 | 100 |
Which Sheet link or tab should I use?
Use the normal docs.google.com/spreadsheets/d/…/edit link, not a “Publish to web” /d/e/…/pubhtml link. To pick a tab precisely, open that tab in a browser and copy its address including gid=….
Source details also lets you switch between discovered tabs. Check your mappings after switching: the column names must still exist. Formulas are read as their exported values, not executed inside WidgetWire.
02 / JSON endpoints
A URL for your data.
An endpoint is a web address that returns data directly—not a dashboard, a login page or an API documentation page. WidgetWire sends an HTTPS GET request to that address.
Get a working endpoint.
Use your service’s data URL, or host the example JSON below on an HTTPS server. Opening the URL should return JSON. Downloading a file to your phone alone does not create an endpoint.
Add it to Sources.
Tap + → JSON / REST API, paste the Endpoint URL, set Authentication if needed, then tap Connect. Public endpoints need no credentials.
Check the rows, then design.
Open the saved source and inspect Columns and Data. With our example, you’ll see four rows and a Value column containing 20, 40, 60 and 80. Continue to your first widget.
[
{"Name":"Design","Value":20,"Percent":0},
{"Name":"Build","Value":40,"Percent":50},
{"Name":"Review","Value":60,"Percent":100},
{"Name":"Launch 🚀","Value":80,"Percent":100}
]Download the complete example JSON ↓
The complete file includes the extra fields needed for every layout recipe. Return a successful HTTP response, ideally with Content-Type: application/json.
Just exploring? Try a public demo endpoint.
No server or key needed. This JSONPlaceholder example is fictional data from a third-party service, not a WidgetWire backend.
https://jsonplaceholder.typicode.com/todos/1Add this URL as JSON / REST API with no authentication. Expect one row with id, title, userId and completed. Create a Stat widget and map its Value slot to id: it should show 1, not the four-row example’s 50.
The demo is read-only sample content and may be unavailable. Replace it with your own endpoint when you’re ready.
Connect an endpoint that needs a key.
Use the method your API provider specifies. Credentials go into Key, not into a widget’s text or template.
- Bearer token
- Enter just the token in Key. WidgetWire adds
Authorization: Bearer …. - Custom header
- Enter the header name, such as
X-API-Key, in Header and the secret in Key. - Query parameter
- Enter the parameter name, such as
api_key, in Parameter and the secret in Key.
Keys are stored in the iOS Keychain; the library stores a reference. Prefer header authentication when available: query keys become part of the request URL and may appear in server logs. Use read-only, narrowly scoped credentials.
OAuth sign-in, POST bodies and automatic token renewal are not supported. Never include keys in a template, screenshot or support message.
Other JSON shapes and field names
The most predictable format is an array of flat objects. Each object is a row; its properties become columns. A single flat object, a one-level wrapper such as {"data":[{"Name":"Design","Value":20}]}, and parallel arrays also work.
Parallel arrays need at least two columns of equal length with more than one item. One nested object of parallel arrays is accepted. If several arrays of objects exist, the first non-empty one by alphabetically sorted key is used.
Deeply nested collections, pagination and JSONPath selection are not supported. Flatten fields or return a small summary from your server. Numbers stay numeric, booleans become true/false, and null or missing cells become empty text.
New JSON sources order columns alphabetically. Refreshes retain existing column order and append new fields. Bind by column name where possible, and keep names and capitalization stable.
03 / Your first connected widget
Let’s see that 50.
Use the four-row spreadsheet or JSON example above. The smaller public demo is different: map id there to see 1.
Start with Stat.
Open Templates, choose Home Screen and Small, then choose Stat.
Attach your saved source.
In the editor’s Content tab, scroll to Data → Connect a Data Source. Select the connection under Your sources. You don’t need to paste its URL again.
Map Value to Value.
Tap the Value content slot. In Map Columns, make sure the column named Value is selected. Tap it only if it isn’t already selected, then tap Done. Auto-mapping is a suggestion; check this choice.
Check the result.
The preview should show 50, the average of 20, 40, 60 and 80. To show one specific value instead, tap Value again, choose Pick a cell and select the cell containing 20. In the example Sheet, that is B2.
Save, then add it to your screen.
Open the phone preview and tap Save Widget. On your Home Screen, touch and hold an empty area, choose Edit → Add Widget, find WidgetWire and choose the matching size. Touch and hold the added widget, choose Edit Widget and select your saved design.
On iOS 17, use the + button at the top of the Home Screen instead of Edit → Add Widget. See Apple’s installation guide for system-specific help.
One cell
Exactly one value, like a total. A1 is a header; A2 is the first data cell. JSON has its own generated grid.
Fixed text
Your own caption or number. In Map Columns, type a fixed value and tap Use. It won’t change with the source.
04 / Pick your next idea
A recipe for every layout.
These recipes use the complete downloadable CSV or JSON file, not the public demo. Read each mapping as “widget slot → source column.” Open just the layouts you need.
Stat One important number
Value → Value. Shows the average, 50. Bind one cell if you want a specific total instead. Caption is optional.
List Rows at a glance
Row label → Name; Row value → Value. Design 20, Build 40, Review 60, Launch 🚀 80, in source order.
Progress, Ring & Gauge A goal taking shape
Percent → Percent. Average 62.5, clamped to 0–100; displayed rounding depends on the layout. Use a cell to follow one goal. Caption is optional.
Split Two numbers together
Left number → Value; Right number → Percent. Two column averages: 50 and 62.5 (the right-hand display rounds to 63).
Sparkline & Columns Change over time
Values → Value. Series 20, 40, 60, 80; latest value 80. Sort the source rows into the order you want to show.
Bars Compare a few things
Bar label → Name; Bar value → Value. One bar per item in source order.
Leaderboard Highest first
Name → Name; Score → Value. Sorted by score, with Launch 🚀 (80) first.
Heatmap A pattern of activity
Intensity → Value. A cell for each numeric value in source order. It is not automatically grouped into calendar dates.
Grid A compact summary
Metric → Value. Count 4, average 50, high 80, low 20.
Status Count each category
Group by → Status. Ready 2, Queued 1, Done 1.
Next Up & Countdown Something to look forward to
Next Up: Title → Name; Date → Date.
Countdown: Event → Name; Date → Date. Uses the nearest date today or later. Replace the example’s January 2027 dates when they are no longer upcoming.
Big Text Words worth keeping
Text → Text; Byline → Name. The first text cell with its caption. A cell binding lets you choose another row.
Dots Little wins, counted
Completion → Percent. 2 of 4 complete. A value of 100 or higher fills a dot; booleans such as true/false do not.
Custom Your own JSON layout
For our full template, map Value → Value; Percent → Percent; Row label → Name; Row value → Value. The template combines the resolved number, meter and repeated rows. Continue to custom layouts.
Keep the data predictable.
- Percentages
- Use 0–100, not 0–1. Prefer a Percent header or values like
50%. Percentage-formatted Google Sheets cells export the displayed percentage. - Numbers
- Use plain numbers for charts. Avoid mixed units, text and a totals row within the same column. Type inference checks non-empty cells in the first 12 rows.
- Dates
- Prefer
YYYY-MM-DD. Dates use the device calendar and time zone; past dates are ignored by upcoming-event layouts. - Column names
- Names are case-sensitive. Renaming a header can break a mapping. If you switch tabs or endpoints, check every content slot again.
05 / More control, when you want it
Data JSON ≠ template JSON.
Data JSON supplies the values. Add its URL in Sources. Template JSON describes the design. Open Templates → Custom, then Edit JSON template. Keep the two separate.
Start with a small template.
Paste the example below in the template editor and tap Done. It displays your mapped Value and Caption.
Connect the data separately.
Back in Content, attach your saved source and map Value to Value. Optionally set Caption to a column or fixed text. With our four-row data, the number is 50.
Preview and save.
Choose a size that suits your layout, inspect the preview, then Save Widget. The in-app Reference lists the supported building blocks.
{
"padding": 18,
"root": {
"type": "vstack",
"align": "leading",
"spacing": 8,
"children": [
{"type":"text","text":"{{value}}","size":36},
{"type":"text","text":"{{caption}}","size":14}
]
}
}Download all-components template JSON ↓
The larger example is designed for Large or Full Screen. It includes all 11 building blocks: vstack, hstack, zstack, text, spacer, divider, bar, ring, symbol, rect and rows.
Use live placeholders in a template.
{{value}}, {{caption}} and {{percent}} use the mapped slots. {{col.Name}} reads the first row’s Name field. Inside a rows block, use {{row.label}}, {{row.value}} and {{row.index}}.
Placeholders are not executable code. Unknown names stay visible to help you spot typos.
Load a design from a URL.
In the template editor, open Examples → Load from URL…. Supply an HTTPS URL that returns template JSON directly. Keeping it linked lets the app re-fetch the design; unlink it to edit a local copy.
Template URLs do not use the data source’s credentials. Use a public, non-sensitive template with no secrets. A template endpoint must return a valid design, not data rows or an HTML repository page.
06 / Know what to expect
Fresh, at iOS’s pace.
After changing your Sheet or endpoint, open Sources → your connection and tap the circular-arrow button (Refresh source). Check Last sync and the Data preview first, then check your widget.
- 200 data rows
- WidgetWire stores the first 200 and reports the full response row count. Calculations use only the stored rows. For a total across thousands of records, return a small pre-aggregated summary.
- 20-second requests
- Each request has a 20-second timeout. A Sheet may need extra metadata requests. Keep responses small and respect your provider’s rate limits.
- Fewer rows on screen
- List, Bars and Leaderboard show up to 3 in Small, 4 in Medium, 8 in Large and 12 in Full Screen. They can calculate from more rows than fit on screen.
- The same data, different sizes
- Connections work across supported Home Screen and Lock Screen layouts. Full Screen authoring uses them too; native placement requires iOS 27 and a compatible WidgetWire build.
07 / Find the step that needs attention
Back on track.
First inspect the source’s Data preview. If it’s wrong there, fix the connection. If it’s right there but wrong in the editor, check the mappings. If the editor is right but the Home Screen is stale, check the selected saved design and allow iOS time to refresh.
Google asks me to sign in.
Check the Sheet link in a signed-out browser. Review General access, Viewer download/export access and any organization restrictions. WidgetWire cannot sign in to a private Sheet. Don’t make sensitive data public to work around this; use a safe, separate dataset.
The wrong tab or rows appear.
Open the intended tab in a browser and copy its URL with the gid. A deleted tab gives an error instead of silently selecting another one. After switching tabs, recheck the column names used by your widget.
I get 401, 403 or an HTML response.
401 usually means missing or invalid credentials; 403 means access was refused. Check Authentication, the header/parameter name and key permissions. HTML usually means a web page or sign-in redirect. Your endpoint must return JSON directly. See authentication setup.
I see an average instead of my total.
A column-bound Stat averages its numeric values. Choose Pick a cell for one specific total, or return a one-row summary from your endpoint. The example’s Value column produces 50; the Sheet’s B2 cell produces 20.
Values are blank, or a meter looks wrong.
Check exact header spelling, capitalization, empty cells and number formats. Percentages use 0–100; 0.5 means half of one percent, not 50%. Dots need numeric completion, not true/false. Re-map fields if the schema changed.
There is no upcoming event.
Next Up and Countdown ignore past dates. Use unambiguous dates such as YYYY-MM-DD and include an event today or later. Update the sample’s January 2027 dates when needed.
The service times out or returns 429.
Check the connection and provider status; reduce the response size. For HTTP 429, wait before trying again. WidgetWire does not follow pagination or continuously poll. Repeated manual refreshes may make a rate limit worse.