Custom widgets

ALPHA: requires Dockset 0.2.7 or later. Features and templates may change.

Create your widget

Open Add Widget → Create Widget in the Dock manager.

1. Data: choose a starter from Use Template. Connect an API or JSON file, or paste sample JSON to try a design.
2. Design: choose the Dock’s main value and add supporting blocks to the Popout. Select a block to edit its fields, label, icon, and format.
3. Review: check both previews, then Save. Use Save Draft to connect a source later.

Sample JSON previews as you type. It stays static until you connect a changing source.

Example templates

1. Download a template and choose ••• → Import Template….
2. In Data, paste its URL, set authentication to None, and choose the refresh interval below.
3. Click Connect and Preview. For templates with a transform, review the code and choose Enable and Preview.
4. Check the design and save.

These examples require no API keys. Public rate limits apply.

https://www.githubstatus.com/api/v2/summary.json

https://api.github.com/repos/swiftlang/swift

https://www.hvakosterstrommen.no/api/v1/prices/{date:yyyy}/{date:MM}-{date:dd}_NO1.json

https://api.exchange.coinbase.com/products/BTC-USD/candles?granularity=3600

https://api.wheretheiss.at/v1/satellites/25544

https://api.socialcounts.org/youtube-live-subscriber-count/YOUR_CHANNEL_ID

https://api.fxtwitter.com/2/profile/YOUR_HANDLE

Format numbers and text

Select a component and open Value formatting. Each block has its own format: use a compact count in the Dock and a full number in the popout.

• Compact number: K, M, B, T; one decimal by default, with trailing zeros hidden.
• Numbers: choose 0–6 decimals and a unit. Currency symbols appear after the minus sign. Separators follow your Mac’s locale; the table uses English.
• Percent: expects a fraction, so 0.75 becomes 75%.
• Date / Time: accepts ISO 8601 or Unix seconds and uses your Mac’s time zone.
• Automatic: keeps plain text. In lists, formatting applies to subtitles.

Icons and colors

In Design → Icon, enable Show icon and pick a symbol or enter an SF Symbol name, such as star. Image URLs and arbitrary brand names are not supported.

• Filled: uses a filled variant when available.
• Icon color: choose from Dockset’s shared palette. Graphs and progress bars have independent colors from the same palette.
• From data: bind the symbol and color to fields in your response. Color values use palette names such as green, orange, and red.

List bindings resolve within each row. Missing colors fall back to the fixed color, then Automatic. Size and spacing controls are under Advanced.

Vertical Docks

Side Docks stack the icon above the value and label. Keep labels short, use compact numbers, and enable wrapping for status text. Put supporting details in the popout.

Text and field bindings

A Metric can show text as well as numbers. Choose Metric and paste this deployment response into sample data:

{
  "release": "v2.4.0",
  "status": "Operational",
  "summary": "The latest release is live in production.",
  "checks": {
    "passed": 18,
    "total": 20
  },
  "changes": [
    {
      "title": "Faster search",
      "detail": "Results load as you type."
    },
    {
      "title": "New exports",
      "detail": "Download reports as CSV."
    }
  ]
}

Download the deployment sample JSON.

The Dock shows v2.4.0 above Release. Keep text on Automatic; use a Text block for longer sentences.

Build a popout

In Design → Popout, add these blocks using the same deployment response:

Use From data for these mappings. List paths are relative to each item: use title, not changes[0].title.

• Fixed value: text or numbers that never change.
• From Configure: a user-editable value. Add text, number, or toggle inputs in Design → Configure first.
• Advanced: text size, wrapping, layout, and spacing.

Time-series graphs

Choose the Graph template to show a visitor trend as a Dock sparkline and a larger chart in the popout. Paste this response to preview it:

{
  "history": [
    { "date": "2026-10-01", "value": 42 },
    { "date": "2026-10-02", "value": 58 },
    { "date": "2026-10-03", "value": 51 },
    { "date": "2026-10-04", "value": 73 }
  ]
}

Download the visitor-history sample JSON.

• Dates: ISO 8601, date-only strings, or Unix seconds/milliseconds. Values must be numeric.
• Points: sorted by date; duplicate dates keep the last value. Empty arrays show an empty state; invalid points show an error.
• History: up to 512 points. Your source must supply them; Dockset does not accumulate readings. Use a transform to aggregate longer histories.

Hover over a chart to inspect a date and value.

Connect an API or file

Choose Source → API endpoint, paste the URL, and click Connect and Preview.

Credentials stay in your Mac’s Keychain. OAuth sign-in and automatic token renewal are not supported.

• Refresh: manual, or every 1, 5, 15, or 60 minutes while the widget’s Dock or editor is active.
• Local scripts: choose a JSON file that your script updates.
• Requests: GET only, over HTTPS or HTTP on localhost. No redirects, request bodies, or write actions. Responses are limited to 1 MB.
• Errors: the last successful data remains visible. Check the URL, authentication, and rate limit, then use Retry.

Dynamic URL values

Use Insert variable beside the endpoint to add the current date or a Configure field. For example:

https://example.com/metrics/{date:yyyy-MM-dd}?project={input:Project}

Replace the example URL with your endpoint. Add Project in Design → Configure. Dates use your Mac’s time zone; input values are URL-encoded. Variables resolve on each request, with the host fixed. Check the result in Request URL.

Reshape a response

Map nested fields directly, such as data.release, or use Data → Transform to simplify a response:

function transform(response) {
  return {
    release: response.version,
    status: response.healthy ? "Operational" : "Needs attention"
  };
}

Click Enable and Preview, then bind fields from the returned JSON.

• Context: transform(response, { now, timeZone, inputs }) provides the current time, Mac time zone, and Configure values.
• Updates: reruns on new data and each minute while active, using cached data without another request. It does not collect history.
• Access: runs locally in a sandbox without network, file, or credential access. Edited or imported code must be enabled again.

Share and troubleshoot

Use ••• → Copy Template or Export Template…. Import with Import Template… or Paste Template.

• Shared: layout text, bindings, Configure field definitions, and transform code.
• Stays local: API URLs, authentication, credentials, response data, and Configure values.

Check layout text and code for private information before sharing.

Troubleshooting

• No value at this path: load a fresh preview and check the field picker. Nested paths use checks.passed; array items use items[0].name.
• List or graph is empty: bind Items or Points to an array, then map fields relative to one item.
• Graph dates or values are invalid: check the Date and Value fields. Convert custom dates or aggregate large arrays with a transform.
• Connection failed: check the URL, authentication, and rate limit before retrying.