Skip to content
AtsuraeDownload

Development sign-in

Only on a local server with DEV_AUTH. Enter any account name.

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

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.svg

src 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.

Format Good for
SVG icons and logos; sharp at any size
PDF 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.

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.

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.

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 }

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.

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.