Quick Start

What's widget.json?

widget.json is a file format designed to push content from the web to your home screen.

With a small amount of JSON, you can create a widget-sized window to your favorite web content.

For a blog, you can make a widget with the latest post title plus a link to go directly to it. For a group of friends, you can make a private, shared scratch pad for notes or images. For developers, you can publish a widget.json from your GitHub Action or other CI. For DIYers, a widget.json could host a professional-looking weather widget powered by their IoT backyard weather station. For Patreon creators, a private widget.json just for your backers. You can make static widgets that simply shows an image you like and then when tapped, launches an iOS Shortcut to FaceTime your grandpa.

Once you've discovered or built a widget.json file that you like, you can use a widget.json client app to fetch and render it. Think of it like RSS for Widgets. Like RSS, widget.json files can be highly dynamic.

Widgets come in different sizes so you can make your home screen look the way you want.

Whatever web content is important to you, widget.json lets you package it up and put it at your fingertips.

For iOS users, Widget Construction Set is an example widget.json client app.

Getting Started

Let's look at a simple hello world widget. Here's what the finished result will look like:

Here's the widget.json that powers it:

That's it!

If you're using Widget Construction Set, you can click here to add hello world directly to your iOS home screen! See Widget Construction Set for details on how one-click widget links work.

We'll be hosting our example widget.json files as GitHub Gists so you can easly fork them and have a hosted widget.json of your own. See if you can remix hello world to say hello to you or change the background color. Here's my remixed hello world widget that I hope my cat River Milk sees.

Here's the widget.json file for it.

Schema Speedrun

Let's take a quick look over what we just saw. To see the full schema overview, check the chapter widget.json Schema.

Starting with the metadata at the top:

{
  "name": "Hello World",
  "description": "My first widget.json.",
  "data": {
    "content_url": "https://wd.gt/"
  },
}

The name and description fields are used in client apps like Widget Construction Set. The data object is a convenient place to template in data that you use across multiple widget layouts. We'll talk more about data in the chapter Anatomy of a Widget. Our data contains only the field content_url. This field is required and will launch the specified URL.

For more details on content_url and other actions a widget can take, see Widget Actions.

Okay, onto the meat of the schema, layouts:

  "layouts": {
    "hello_small": {
      "size": "small",
      "styles": {
        "colors": {
          "cool_purple": {
            "color": "#626DFF"
          }
        }
      },
      "layers": [
        {
          "rows": [
            {
              "height": 12,
              "cells": [
                {
                  "width": 12,
                  "background_color_style": "cool_purple",
                  "text": {
                    "string": "hello world"
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  }

Specifying layouts is the bulk of any widget.json file. Even in our simple example, the presentation instructions are the majority. We've got a whole chapter on Widget Layout, but here's a quick overview.

layouts is a dictionary of different layout objects. Here we only specify a single layout called hello_small. You can call the layout whatever you want, but you'll see that this name will be used in other parts of the schema later to hint clients how to show your layouts. You need to specify at least one valid layout, but you can have more. For example, you might present more data on a large size widget or maybe you offer another small widget with a different color scheme.

Once you have a layout name, you need to specify a layout size. See the chapter widget.json Schema for details.

Next, we can define some optional styles. These come in the form of colors and fonts. We're only using colors here. We define a new color called cool_purple. You can see further down we use cool_purple on the property background_color_style.

Lastly, we have a layers array. Each layer is drawn on top of the last. To make the grid easily divisible, layers are 12x12 units. You can see our first and only layer has one row with height 12 and that one row has one cell with width 12. Cells are the fundamental unit of content in widget.json. This first cell ends up taking up the entire layer and turning it cool_purple. This cell also places a text object with the content hello world into our widget.

What's Next

Now that we have the fundamentals of widget.json, take a look at Anatomy of a Widget to see what an actually useful widget might look like. To learn more about laying out a widget, take a look at Widget Layout.