Your data.
On your screen.

A quick orientation

Connect once.
Make it yours.

1. 01
   Add a source

   A source is the Sheet or endpoint WidgetWire reads. One source can power several widgets.

2. 02
   Choose what to show

   Mapping connects a widget’s content slot—like Value or Caption—to a column or one cell.

3. 03
   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.

1. 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.

2. 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

3. 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.

4. 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.

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.

1. 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.

2. Add it to Sources.

   Tap + → JSON / REST API, paste the Endpoint URL, set Authentication if needed, then tap Connect. Public endpoints need no credentials.

3. 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.

https://jsonplaceholder.typicode.com/todos/1

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.

1. Start with Stat.

   Open Templates, choose Home Screen and Small, then choose Stat.

2. 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.

3. 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.

4. 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.

5. 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.

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.

Keep the data predictable.

Ready-made background templates start with editable personal content; no connection or layout JSON is required. Basic layout previews show examples until you add your values. Required fields must be filled before saving; captions and bylines marked Optional can stay empty. Lock Screen widgets use compact monochrome summaries, not the full Home Screen design.

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.

1. Start with a small template.

   Paste the example below in the template editor and tap Done. It displays your mapped Value and Caption.

2. 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.

3. 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.

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.

Back to the guide ↑