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:
- Touch and hold anywhere on your home screen until the apps jiggle;
- Tap the Add (+) button in the upper-left corner;
- Look for Pushcut on the apps list and tap on it;
- Pick a size you want and tap on Add Widget;
- Tap on your newly added widget to open its configuration;
- Choose which Pushcut Widget you'd like to display and what action should happen when you tap on the widget;
- 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:
|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.|
|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.
Each Component has many Properties that allow you to fine tune how it is rendered. Pushcut currently supports the following properties:
|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.|
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.
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.
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.
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!
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
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
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
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
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.
||The name of the content you'd like to display||string|
||The inputs passed to the widget (like
||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|
||The action to take when the widget is tapped||an object describing the action (e.g.
On Tap Actions
||The action to take. Valid options are
||The name of the shortcut to run, if
||The input to provide to a shortcut if the action is
||The url to open, if
||Whether the action should run on your Automation Server, if
You might get one of the following error codes when something is wrong with the request:
|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:
- Make sure no errors were returned, specially if you are using webhooks;
- Double check if you have internet connectivity: widget updates require internet connection, even when using the Shortcuts Action;
- Ensure Pushcut has Background App Refresh permission: go to your device Settings, search for Pushcut and activate Background App Refresh;
- Wait 10 to 15 minutes: sometimes iOS may take a while to update your widgets;
- Open the Pushcut app and see if the widget gets updated (this may cause iOS to prioritize the widget update);
- 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;
- Try updating your widgets with your device connected to a Wi-Fi network (iOS seems to refresh widgets more frequently when using Wi-Fi).