Scriptable iOS Widgets

Appearance

📲 Installation Guide ​

Get started with Scriptable iOS Widgets in just a few simple steps!

Installation Preview

📱 Prerequisites ​

Before you begin, make sure you have:

  • iOS 14 or later (required for widgets)
  • Scriptable app (free from App Store)
  • Internet connection (for API-based widgets)

🚀 Step-by-Step Installation ​

1. Install Scriptable App ​

  1. Open the App Store on your iOS device
  2. Search for "Scriptable"
  3. Download and install the app (it's free!)
  4. Open Scriptable to complete setup

2. Choose Your Widget ​

Browse our widget collection and pick the one you want to install. Each widget has:

  • Detailed documentation with setup instructions
  • Configuration options for customization
  • Source code ready to copy and paste

3. Copy Widget Code ​

  1. Visit the widget's documentation page
  2. Click the "View Source Code" link
  3. Copy the entire JavaScript code
  4. Keep it in your clipboard

4. Create Script in Scriptable ​

  1. Open the Scriptable app
  2. Tap the "+" button to create a new script
  3. Paste the copied code
  4. Rename the script (e.g., "Weather Widget")
  5. Tap "Done" to save

5. Configure Widget Settings ​

Most widgets require some configuration:

  • API keys (for weather, GitHub stats, etc.)
  • Personal information (birth dates, usernames, etc.)
  • Preferences (colors, display options, etc.)

Follow the specific instructions in each widget's documentation.

6. Test the Widget ​

  1. Tap the play button in Scriptable
  2. Verify the widget displays correctly
  3. Check for any error messages
  4. Make adjustments if needed

7. Add to Home Screen ​

  1. Long press on your home screen
  2. Tap the "+" in the top-left corner
  3. Search for "Scriptable"
  4. Choose your preferred widget size
  5. Tap "Add Widget"
  6. Tap the widget to configure it
  7. Select your script and adjust settings
  8. Tap outside to finish

⚙️ Widget Configuration ​

Accessing Widget Settings ​

After adding a widget to your home screen:

  1. Long press the widget
  2. Select "Edit Widget"
  3. Choose your script
  4. Set parameters if needed
  5. Tap "Done"

Common Settings ​

Most widgets support these parameters:

  • Script: Choose which Scriptable script to run
  • When Interacting: Choose "Run Script" or "Open App"
  • Parameter: Optional text for widget customization

🔧 Troubleshooting ​

Widget Not Loading ​

Check these common issues:

  • ✅ Script is saved in Scriptable
  • ✅ Required API keys are configured
  • ✅ Internet connection is available
  • ✅ Location permissions granted (if needed)
  • ✅ Widget size matches script requirements

Error Messages ​

"Script not found":

  • Ensure script name matches exactly
  • Check for typos in script selection

"API Error" or "Network Error":

  • Verify API keys are correct and active
  • Check internet connection
  • Try running script manually in Scriptable

"Permission Denied":

  • Enable location services for Scriptable
  • Grant necessary permissions in iOS Settings

Performance Issues ​

Widget loading slowly:

  • Check internet connection speed
  • Reduce refresh frequency if configurable
  • Clear Scriptable app cache

Battery drain:

  • Widgets update automatically on schedule
  • Most widgets are optimized for efficiency
  • Consider reducing update frequency for complex widgets

📚 Advanced Tips ​

Multiple Widget Instances ​

You can have multiple instances of the same widget:

  1. Duplicate the script in Scriptable
  2. Configure each differently (different locations, users, etc.)
  3. Name them uniquely (e.g., "Weather Home", "Weather Work")
  4. Add separate widgets to home screen

Widget Sizes Guide ​

SizeDimensionsBest ForTypical Content
Small2x2Quick infoTemperature, single stat
Medium4x2Balanced viewWeather + forecast
Large4x4Detailed infoFull dashboard

Customization Tips ​

  • Read the documentation for each widget thoroughly
  • Test configurations in Scriptable before adding to home screen
  • Start with defaults and customize gradually
  • Join the community for tips and custom configurations

🔄 Updating Widgets ​

Manual Updates ​

  1. Copy new code from the repository
  2. Open existing script in Scriptable
  3. Replace old code with new version
  4. Update configuration if needed
  5. Test before using

Automatic Updates ​

Currently, widgets don't auto-update. We recommend:

  • Star the repository to get notified of updates
  • Check back periodically for new features
  • Follow release notes for breaking changes

🆘 Getting Help ​

Documentation ​

  • Widget-specific docs: Each widget has detailed setup instructions
  • Troubleshooting guides: Common issues and solutions
  • Configuration examples: Sample setups and customizations

Community Support ​

Before Asking for Help ​

Please include:

  • Widget name and version
  • iOS version and device model
  • Error messages (screenshots help!)
  • Configuration details (remove sensitive info like API keys)
  • Steps to reproduce the issue

🎉 You're All Set! ​

Congratulations! You should now have beautiful, functional widgets on your iOS home screen.

What's next?

  • Explore more widgets from our collection
  • Customize colors and settings to match your style
  • Share your setups with the community
  • Consider contributing improvements or new widgets

Enjoy your enhanced iOS experience! 📱✨