Support

Widgets

Unlock the full potential of Pushcut dynamic Widgets. Want some ideas? See our example widgets!

Widgets and Contents

Use the Add Widget (Widget Editor) view to create new Widgets and the Add Content (Content Editor) view to create beautiful designs to display their content.

Each Pushcut Widget can only display one Content at a time, but you can dynamically change the Content and the information it contains using the Update Widget Shortcuts Action, one of our supported Integration Services or by providing a JSON object to the widget's webhook. Read more about updating your widgets on the How to update your Widgets section.

To add one of your Pushcut widgets to your home screen, follow these steps:

  1. Touch and hold anywhere on your home screen until the apps jiggle;
  2. Tap the Add (+) button in the upper-left corner;
  3. Look for Pushcut on the apps list and tap on it;
  4. Pick a size you want and tap on Add Widget;
  5. Tap on your newly added widget to open its configuration;
  6. Choose which Pushcut Widget you'd like to display and what action should happen when you tap on the widget;
  7. Tap outside the window and, then, tap on the Done button on the upper-right corner.

Creating, using and updating Pushcut Widgets require a Pro Subscription.

On Tap Actions

Tapping a widget opens Pushcut—this is required by Apple, but you can choose exactly what each widget does when you tap on it:

Action Description
Open Pushcut This opens the Pushcut app, don't forget you can set your default view on startup
Run Shortcut Choose to run a shortcut, provide input, and specify if you'd like this to run on your automation server instead.
Open URL If you want to integrate with an app that doesn't support Shortcuts or a website, you can open a URL (scheme).
Run HomeKit Scene Turn on your lights, pause all the speakers or do anything through a HomeKit scene.
Run Integration Trigger an IFTTT, Make.com or Zapier automation from your integrations.

Components

Component Description
Column Container that fills all available space in both directions and organizes child components vertically.
Row Container that fills all available space in both directions and organizes child components horizontally.
Text Displays a string of markdown text.
Symbol Displays the specified SF Symbol.
Spacer A special type of component that fills all available space in a given direction.

To add a component to your Content, either choose from the list provided when the Content is empty or tap the + button on the right side of a Container Component, such as a Column or a Row.

Properties

Each Component has many Properties that allow you to fine tune how it is rendered. Pushcut currently supports the following properties:

Property Description
Spacing Exclusive to Containers. Controls how far apart the child components are placed.
Fill Direction Exclusive to Containers. Defines if the container occupies all available space in all directions, only on a specific direction (vertically or horizontally) or if it fits to its content.
Vertical Alignment Exclusive to Rows. Defines the relative vertical alignment between the child components.
Horizontal Alignment Exclusive to Columns. Defines the relative horizontal alignment between the child components.
Spacer Direction Exclusive to Spacers. Defines the direction in which the spacer extends (horizontal, vertical or both).
Value The actual value of the component, for example, the Text string or SF Symbol reference to be displayed.
Font Modifies the font family, size, color, weight and design (if the font is San Francisco). By default any child component inherits the font properties defined on its parents.
Background Applies a background color or gradient to the component.
Padding Applies a padding to the component.

Inputs

Much like Pushcut Notifications, an Input is a representation of a dynamic variable that the user can provide to Pushcut so that the Widget can display new information whenever it's updated.

All components that have a value property, allow you to include a special input variable on it by tapping on the + Input button. Pushcut will automatically insert an Input Marker into the component value, represented by the [[input]] placeholder. Since Pushcut supports multiple inputs per Widget, each input marker will be progressively numbered so that it can be uniquely identified.

The next time you trigger an update to this particular widget, either by using the Update Widget shortcuts Action, one of our supported Integration Services or the widget's webhook, you can pass new values to each of the previously defined inputs as parameters of the action or as a JSON object.

If the value passed as an input contains the placeholder [[clipboard]], this will be replaced with the contents of the clipboard on this device on which the widget is tapped.

Sharing Contents

Contents are fully based on JSON objects, so they can be easily shared in Pushcut! To share your favorite content designs with the community, just open it and tap the Share Button in the toolbar to copy its JSON.

Widget Content Toolbar

To import a design, just tap the Import Button and choose either from the clipboard or from a file!

How to update your Widgets

Pushcut Widgets can be dynamically updated in order to change the currently displayed Content or provide it with new inputs. Keep in mind that, in order to preserve battery life, iOS maintains a very strict control on how and when your home screen widgets are updated, so it may take some minutes for you to see the update you requested on your home screen. You can read more about these restrictions on the Troubleshooting widget updates section.

Update Widget Shortcuts action

Pushcut now includes a new Shortcuts action that allows you to change a widget content and provide multiple inputs. This action is the perfect option to use with Shortcuts Automations, making it possible to schedule widget updates based on many different criteria, such as time of day and location.

Integration services

When the information that you need to display on your widget comes from an online service, relying on an integration service is your best bet. Pushcut currently supports triggering widget updates via Zapier and we're working on bringing this new feature to IFTTT and Make soon!

Webhooks

Similar to Notifications, each Widget has an associated HTTP webhook that allows you to trigger your notifications by sending a POST or GET request to a secret, unique URL. This URL can be seen and copied on the Widget Editor view and looks similar to https://api.pushcut.io/[secret]/widgets/[widget-name. There is also an option to copy a curl statement. The command line utility curl runs on most servers as well as Macs and PCs - simply execute the statement on the command line to trigger your notification.

Triggering a widget update with a GET request can be convenient, since you can even do it straight from a web browser. However, you can have more control over the update by sending a POST request with an attached JSON body, which allows you to provide dynamic inputs or choose which of your devices should receive the update.

Make sure to set the Content-Type to application/json and that correct quotes are used! If you have the Smart Punctuation (iOS) or Smart Quotes (macOS) feature turned on, your quotes might look like „text“ or “text”. This is not valid JSON and will not work. Make sure your quotes look like this: "text"

Here is a list of JSON keys that are supported - they are all optional. Any other key will be ignored.

Key Value Type
content The name of the content you'd like to display string
inputs The inputs passed to the widget (like {"input0": "first_value", "input1": "second_value"}) {"input0": string, "input1": string, ...} object
devices A list of device names this update should be sent to (you can see the names of devices linked to your account in the app's Account view) array of strings
onTap The action to take when the widget is tapped an object describing the action (e.g. {"action": "runShortcut", "shorcutName": "MyShortcut"} see "On Tap Actions" below
On Tap Actions
Key Value Type
action The action to take. Valid options are openPushcut, runShortcut, runHomeKitScene, or openURL string
shortcutName The name of the shortcut to run, if action is runShortcut. Ignored otherwise string
shortcutInput The input to provide to a shortcut if the action is runShortcut. Ignored otherwise string
url The url to open, if action is openURL. Ignored otherwise string
shouldRunOnServer Whether the action should run on your Automation Server, if action is runShortcut or runHomeKitScene. Ignored otherwise boolean

Error codes

You might get one of the following error codes when something is wrong with the request:

HTTP Code Message Reason
404 Not Found Invalid secret. The secret does not belong to an active account.
404 Not Found Invalid widget name. No widget is defined with this name.
400 Bad Request Specified device names invalid. At least one of the device names was not found in your account.
400 Bad Request Bad Request Something is wrong with the request, likely a malformed JSON body.
500 Internal Server Error An internal server error occured. Please try again, or contact us if this problem persists.

Troubleshooting Widget updates

If your widgets are not being updated after using one of the methods described on the How to update your Widgets section or if it's taking longer than expected, try to follow these steps:

  1. Make sure no errors were returned, specially if you are using webhooks;
  2. Double check if you have internet connectivity: widget updates require internet connection, even when using the Shortcuts Action;
  3. Ensure Pushcut has Background App Refresh permission: go to your device Settings, search for Pushcut and activate Background App Refresh;
  4. Wait 10 to 15 minutes: sometimes iOS may take a while to update your widgets;
  5. Open the Pushcut app and see if the widget gets updated (this may cause iOS to prioritize the widget update);
  6. Make sure your battery level is high and your device is not on low power mode: iOS throttles widget updates when low on battery, specially when low power mode is activated, which disables Background App Refresh;
  7. Try updating your widgets with your device connected to a Wi-Fi network (iOS seems to refresh widgets more frequently when using Wi-Fi).