Add big Home Screen icons that run Shortcuts on iPad
Use a Scriptable widget to place a large custom image on the iPad Home Screen and run an iOS Shortcut when you tap it.
Overview
- This guide shows how to put a large custom image on the iPad Home Screen that runs an iOS Shortcut when you tap it.
- Goal: add a big, tappable icon for a Shortcut without relying on the default Shortcuts app icon.
- The setup uses the free Scriptable app and a short JavaScript widget script.
- Target audience: iPad users who already use Shortcuts and want larger, custom Home Screen launchers.
Preparations
Install Scriptable
- Open the App Store on your iPad.
- Search for Scriptable, then install Scriptable.
Scriptable runs JavaScript on the device and can draw Home Screen widgets.
Create or choose a Shortcut
- Open the Shortcuts app.
- Create a new Shortcut, or note the exact name of an existing one.
- Name it
Example Shortcutfor this walkthrough, or keep your own name and update the script later.
The widget opens the Shortcut by name, so the string in the script must match the Shortcuts app exactly.
Prepare a widget image
Pick a square or near-square image that reads clearly at widget size. Medium and large Home Screen widgets work best for a "big icon" look on iPad.
Steps to add a big Shortcut icon
Step 1: Add the Scriptable script
- Open Scriptable.
- Tap + to create a new script.
- Paste the widget script below into the editor.
- If your Shortcut name is not
Example Shortcut, change theSHORTCUT_NAMEvalue near the top of the script so it matches the Shortcuts app exactly. - Tap Done or the close control to save the script.
- Rename the script in Scriptable to something you will recognize later, such as
Example Shortcut icon.
Caution: Do not rename the script after you choose its image.
The saved image is named after the script, so a renamed script can no longer find it, and the widget shows "Open Scriptable and run this script once." again. If you rename the script, run it again and choose the image again.
Step 2: Choose the widget image
- Open the script in Scriptable.
- Tap the Play button to run it inside the app.
- When the photo picker appears, select the image you prepared.
- When Scriptable asks for a preview size, choose the widget size you plan to add, such as Medium or Large.
- Confirm the preview that Scriptable shows.
Running the script once inside Scriptable shrinks the image to widget size and saves it to Scriptable's local files. The Home Screen widget needs that saved file.
Step 3: Add the Scriptable widget to the Home Screen
- On the iPad Home Screen, touch and hold an empty area until the apps jiggle.
- Tap Edit in the top-left corner, then tap Add Widget.
- Search for Scriptable, then choose a medium or large widget size.
- Tap Add Widget, then tap Done.
- Touch and hold the new widget, then tap Edit Widget.
- Set Script to the script you created.
- Leave the other options at their defaults unless you already use Scriptable parameters.
- Tap outside the configuration sheet, then tap Done if the Home Screen is still in jiggle mode.
The widget should fill with your custom image. Tap it to run the Shortcut named in SHORTCUT_NAME.
Widget script
// CHANGE THIS to the exact name of your Apple Shortcut.
const SHORTCUT_NAME = 'Example Shortcut';
// Longest side, in pixels, of the saved image.
// Widgets have little memory, so full-size photos can render blank.
const MAX_IMAGE_SIZE = 1000;
const fm = FileManager.local();
// Each script saves its own image, named after the script.
const imagePath = fm.joinPath(fm.documentsDirectory(), Script.name() + '.png');
// Build the widget, or a reminder to pick an image if none is saved yet.
function createWidget(image) {
const widget = new ListWidget();
if (!image) {
widget.addText('Open Scriptable and run this script once.');
return widget;
}
// Use the selected picture as the entire widget background.
widget.backgroundImage = image;
// Remove unnecessary internal spacing.
widget.setPadding(0, 0, 0, 0);
// Tapping anywhere on the widget runs the Apple Shortcut.
widget.url =
'shortcuts://run-shortcut?name=' + encodeURIComponent(SHORTCUT_NAME);
return widget;
}
// Shrink the image so its longest side is at most MAX_IMAGE_SIZE.
function resizeImage(image) {
const { width, height } = image.size;
const scale = MAX_IMAGE_SIZE / Math.max(width, height);
if (scale >= 1) {
return image;
}
const size = new Size(Math.round(width * scale), Math.round(height * scale));
const context = new DrawContext();
context.size = size;
context.opaque = false;
context.respectScreenScale = false;
context.drawImageInRect(image, new Rect(0, 0, size.width, size.height));
return context.getImage();
}
// Let you choose a new image. Returns null if you cancel the picker.
async function pickImage() {
try {
return resizeImage(await Photos.fromLibrary());
} catch {
return null;
}
}
function loadSavedImage() {
return fm.fileExists(imagePath) ? fm.readImage(imagePath) : null;
}
// Preview the widget at the size you use on the Home Screen.
async function previewWidget(widget) {
const alert = new Alert();
alert.title = 'Preview';
alert.message = 'Choose the widget size you use on the Home Screen.';
alert.addAction('Small');
alert.addAction('Medium');
alert.addAction('Large');
alert.addCancelAction('Skip');
const choice = await alert.presentAlert();
if (choice === 0) {
await widget.presentSmall();
} else if (choice === 1) {
await widget.presentMedium();
} else if (choice === 2) {
await widget.presentLarge();
}
}
if (config.runsInApp) {
// When you manually run this script inside Scriptable,
// let you choose or replace the widget image.
// Cancel the picker to preview the saved image again.
const pickedImage = await pickImage();
if (pickedImage) {
fm.writeImage(imagePath, pickedImage);
}
const image = pickedImage ?? loadSavedImage();
if (image) {
await previewWidget(createWidget(image));
}
} else {
// When iOS runs this as a Home Screen widget:
Script.setWidget(createWidget(loadSavedImage()));
}
Script.complete();Additional information
- Add more icons. Duplicate the script in Scriptable for each Shortcut. Give every copy a unique name and its own
SHORTCUT_NAME, then run each copy once to pick its image. Each copy saves its image under its own script name, so the widgets do not overwrite each other. - Change the image later. Open the script in Scriptable and run it again. The photo picker replaces the saved image, and the widget updates on the next refresh. To preview the current image without replacing it, cancel the photo picker.
- Widget size. The same script works for small, medium, and large Scriptable widgets. Medium and large sizes look closest to oversized app icons on iPad.
Troubleshooting
The widget shows "Open Scriptable and run this script once."
The widget has no saved image yet, or the script was renamed after the image was saved. Open the script in Scriptable, run it with Play, and choose an image.
Tapping the widget does nothing, or the wrong Shortcut runs
Confirm that SHORTCUT_NAME matches the Shortcut name in the Shortcuts app, including capitalization and spacing. Rename either the Shortcut or the constant, save the script, then edit the widget and select the script again.
The widget is blank or shows an old image
- Run the script once inside Scriptable to rewrite the saved image.
- Touch and hold the widget, tap Edit Widget, and confirm the correct script is selected.
- Restart the iPad if the widget still does not refresh.
Scriptable asks for Photos access
Allow Photos access when prompted. The in-app run uses Photos.fromLibrary() to pick the widget image.