FAQ
Making widgets
Section titled “Making widgets”Do I need to know how to program?
Section titled “Do I need to know how to program?”No. Most widgets are just JSON: a list of elements with tokens like {time}. JavaScript is optional, for values tokens don’t provide.
Why JSON and JavaScript, not Swift?
Section titled “Why JSON and JavaScript, not Swift?”So anyone can make a widget with a text editor, without Xcode, compiling or learning a new language. JavaScript is the most widely known programming language, and it’s sandboxed, so shared widgets are safe.
Can a widget load data from the internet, like stock prices or my calendar?
Section titled “Can a widget load data from the internet, like stock prices or my calendar?”Not yet. Scripts have no network access, which is what makes shared widgets safe to install. Atsurae provides weather itself. If there’s data you’d like, tell us.
Can widgets be animated?
Section titled “Can widgets be animated?”No. Widgets redraw only when their content changes, which keeps them almost free to run. A clock with seconds updating once a second is as fast as it gets.
Can people click or interact with widgets?
Section titled “Can people click or interact with widgets?”No. Widgets are click-through so they never get in the way of your desktop.
Can text wrap onto several lines?
Section titled “Can text wrap onto several lines?”No; each text element is one line. Use one element per line.
Can I use my own fonts?
Section titled “Can I use my own fonts?”Yes, put .ttf or .otf files in the package’s fonts/ folder. See Fonts.
Can a widget show different images depending on data?
Section titled “Can a widget show different images depending on data?”Yes: one image element per picture, each with visibleWhen based on a script value. See Showing and hiding elements.
How do I show the time in another time zone?
Section titled “How do I show the time in another time zone?”With a script and toLocaleTimeString({ timeZone }). See the World Clock.
What’s the smallest possible widget?
Section titled “What’s the smallest possible widget?”{ "formatVersion": 2, "id": "hi", "name": "Hi", "elements": [{ "text": "Hi" }] }Can I make a widget bigger than the screen, or put it off-screen?
Section titled “Can I make a widget bigger than the screen, or put it off-screen?”Placements stay on screen; elements can extend beyond the edges, but they’ll be cut off.
Using widgets
Section titled “Using widgets”Where are my widgets stored?
Section titled “Where are my widgets stored?”In ~/Library/Application Support/Atsurae/Widgets. Widgets from the community are in its Community folder. Positions and settings are stored separately, by widget ID.
Can I use the same widget twice?
Section titled “Can I use the same widget twice?”Not yet; each widget has one placement. To show two copies, duplicate it with a different id.
Do widgets show on all my displays?
Section titled “Do widgets show on all my displays?”On the main display, on every Space.
Do widgets show on the lock screen?
Section titled “Do widgets show on the lock screen?”No. The lock screen is drawn by macOS and shows its own clock. See Desktop only.
Do widgets drain my battery?
Section titled “Do widgets drain my battery?”Barely. Three text widgets add about 5 MB of memory and no measurable CPU. See Performance and battery.
Why does a widget show “Song Title” in the Library but nothing on my desktop?
Section titled “Why does a widget show “Song Title” in the Library but nothing on my desktop?”Previews fill in example values for missing data (nothing playing, no battery, no weather yet). The desktop shows only real values.
Why is the weather empty?
Section titled “Why is the weather empty?”Location access is off and no city is set in Atsurae Settings ▸ Weather, or the weather hasn’t loaded yet. Customize Widgets shows the reason when a weather widget is selected.
Is it safe to install widgets from the community?
Section titled “Is it safe to install widgets from the community?”Widget scripts can’t use the network, read files or access your Mac, and each run is limited to 0.25 seconds. See Safety.
How do I remove a widget?
Section titled “How do I remove a widget?”Right-click its card in the Library and choose Move to Trash.
Sharing
Section titled “Sharing”Do I need to buy Atsurae to share widgets?
Section titled “Do I need to buy Atsurae to share widgets?”Uploading needs the full version. Browsing and downloading are free, including during the trial.
Can I sell widgets?
Section titled “Can I sell widgets?”Not through Atsurae. Community widgets are free to download.
How long does review take?
Section titled “How long does review take?”Usually within a day. Your upload shows In Review in the Uploads tab until a moderator approves it, or Rejected with their reason.
Someone copied my widget. What can I do?
Section titled “Someone copied my widget. What can I do?”Report it from its page in Discover.
