Packages
A widget is either a single .json file or a package: a folder whose name ends in .atsuraewidget.
Single file
Section titled “Single file”A widget that only uses text, shapes and progress bars can be one file:
~/Library/Application Support/Atsurae/Widgets/└── Big Clock.jsonThe file name doesn’t matter; the id and name inside do.
Package
Section titled “Package”A widget with a script, images or fonts must be a package:
World Clock.atsuraewidget/├── widget.json required├── script.js if "script" is set├── images/ images used by "src"│ └── globe.svg├── fonts/ .ttf or .otf files, available by family name│ └── Inter-Regular.ttf└── LICENSE.txt licenses for fonts and images you includewidget.jsonmust be at the top of the folder, with exactly that name.- The folder can have any name ending in
.atsuraewidget. Finder shows the extension like a file type. imagesandfontsare conventions for images, and a requirement for fonts: Atsurae loads fonts only fromfonts/.- Anything else in the folder (licenses, a README, source files for your images) is ignored by Atsurae but kept when you share the widget.
Even a widget that doesn’t need a package can be one; the examples on this site all are.
Turning a file into a package
Section titled “Turning a file into a package”- Make a folder called
My Widget.atsuraewidget. - Move your
.jsonfile into it and rename it towidget.json.
Where widgets live
Section titled “Where widgets live”~/Library/Application Support/Atsurae/Widgets/├── Big Clock.json├── World Clock.atsuraewidget/└── Community/ widgets you got from Discover (managed by Atsurae)Atsurae loads every .json file and .atsuraewidget folder at the top of this folder. Subfolders that aren’t packages are ignored, except Community, which holds widgets downloaded from the community. Don’t edit those; changes are lost when the widget is reinstalled. Copy one out to the main folder to make your own version, and give it a new id.
Installing a widget
Section titled “Installing a widget”Any of these work:
- Drag a
.atsuraewidgetfolder, a.jsonfile or a.ziponto the Widgets section of your Library. - Library ▸ Widgets ▸ Add ▸ Import Widget… and choose one.
- Copy it into the widgets folder yourself.
Imported widgets are copied into the widgets folder (zips are unpacked first) and turned on. If the name is taken, Atsurae adds a number.
Removing a widget
Section titled “Removing a widget”Right-click its card in the Library and choose Move to Trash, or delete it from the widgets folder. Atsurae keeps the widget’s position and settings, so putting it back restores them.
Sharing a widget yourself
Section titled “Sharing a widget yourself”To send a widget to a friend, zip the package (right-click ▸ Compress) and send the zip. They drop it on their Library. To share with everyone, publish it to the community.
The id is how Atsurae tells widgets apart. It must be unique among all your widgets, using lowercase letters, numbers and dashes:
"id": "world-clock"- Two widgets with the same
idcan’t both load; the second one shows an error. - A user widget can’t use a built-in’s ID (
day,date,time,now-playing,system,custom-text). - Placement, size, color and option values are stored by
id. Keep it the same across versions of your widget, and pick something distinctive (sam-world-clock) if you plan to share it.
