Images
Image elements draw a file from your widget’s package:
{ "type": "image", "src": "images/moon.png", "size": [0.05, 0.05] }| Field | Required | Meaning |
|---|---|---|
type |
yes | "image" |
src |
yes | The file’s path inside the widget’s folder |
size |
yes | [width, height] as fractions of the screen height |
tint |
no | Fills the image’s shape with one color |
cornerRadius |
no | Rounds the corners (fraction of the screen height) |
opacity, offset, alignment, shadow, visibleWhen |
no | As for any element |
Where images go
Section titled “Where images go”Images must be inside the widget’s package, so the widget needs to be a .atsuraewidget folder. By convention they go in an images folder:
Moon Phase.atsuraewidget/├── widget.json└── images/ ├── moon.png └── star.svgsrc is relative to the package: "images/moon.png". Atsurae can’t load images from the web or from elsewhere on your Mac. That keeps widgets self-contained and safe to share.
Formats
Section titled “Formats”| Format | Good for |
|---|---|
| SVG | icons and logos; sharp at any size |
| vector art exported from design apps; sharp at any size | |
| PNG | icons with transparency, pixel art |
| JPEG, HEIC | photos |
| GIF | shows the first frame only (no animation) |
Atsurae decodes each image at exactly the size it’s drawn (taking the display’s Retina scale into account), so a large file doesn’t use more memory than a small one. Still, keep files reasonably small: packages you share are limited to 10 MB.
Fitting
Section titled “Fitting”The image is scaled to fit inside size without stretching. If the image’s shape differs from size, there’s empty space on two sides. Match size to your image’s aspect ratio: a 400×200 image fits [0.1, 0.05] exactly.
Tinting icons
Section titled “Tinting icons”For single-color icons, set a tint. Atsurae uses the image’s shape (its transparency) and fills it with the color:
{ "type": "image", "src": "images/note.svg", "size": [0.026, 0.026], "tint": "#FF4F8B" }The original colors don’t matter, only where the image is opaque. Tinted images also follow the color people pick in Customize Widgets, just like text. Images without a tint always keep their own colors.
Rounded corners
Section titled “Rounded corners”cornerRadius clips the image to a rounded rectangle, nice for album-art-style pictures:
{ "type": "image", "src": "images/cover.jpg", "size": [0.08, 0.08], "cornerRadius": 0.01 }Changing images with data
Section titled “Changing images with data”The src is fixed. To switch between images, add one element per image and show one at a time with visibleWhen:
{ "type": "image", "src": "images/sun.svg", "size": [0.04, 0.04], "visibleWhen": "{script.isDay}" },{ "type": "image", "src": "images/moon.svg", "size": [0.04, 0.04], "visibleWhen": "{script.isNight}" }with a script returning { isDay: true, isNight: false } (or the other way round). See Showing and hiding elements.
Problems
Section titled “Problems”| Message | Fix |
|---|---|
| elements[0] needs a “src”, the image’s path in the widget’s folder. | Add src. |
| elements[0]: the image “images/moon.png” isn’t in the widget’s folder. | Check the file name and folder; paths are case-sensitive on some disks. |
| elements[0] uses an image, so the widget must be a folder (.atsuraewidget) with the image inside. | Turn your .json into a package. |
| elements[0] needs a “size”, like [0.1, 0.1]. | Add size. |
