Skip to content
AtsuraeDownload

Development sign-in

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

Layout and alignment

A widget can have as many elements as it needs. They’re all positioned relative to the widget’s anchor (the point people drag in Customize Widgets) with offset and alignment. If you haven’t yet, read Position and size first.

  1. offset: [x, y] moves an element from the anchor, in fractions of the screen height. Positive y goes down.
  2. Every element is centered vertically on its offset point.
  3. alignment says which part of the element sits on the offset point horizontally: "center" (default), "leading" (left edge) or "trailing" (right edge).
  4. Elements draw in order; later ones are on top.

The most common layout: a big value with a label under it. Text is centered vertically, so space elements by roughly half of each one’s font size plus a gap:

"elements": [
{ "text": "{hour}:{minute}", "font": { "size": 0.16, "weight": "ultraLight" } },
{ "text": "{weekday}, {monthName} {day}", "font": { "size": 0.022 }, "offset": [0, 0.11] }
]

The clock is 0.16 tall, so its bottom is about 0.08 below the anchor; the date (0.022 tall, so 0.011 above its center) sits at 0.11, leaving a small gap. Adjust by eye; live reload makes this quick.

Put elements side by side with x offsets. With center alignment, an element’s middle sits on its offset:

{ "text": "☀︎", "font": { "size": 0.04 }, "offset": [-0.05, 0] },
{ "text": "21°", "font": { "size": 0.04 }, "offset": [0.03, 0] }

For text of varying width, anchor each item at its edge instead, so a growing value doesn’t overlap its neighbor:

{ "text": "☀︎", "font": { "size": 0.04 }, "alignment": "trailing", "offset": [-0.01, 0] },
{ "text": "{weather.temperature}", "font": { "size": 0.04 }, "alignment": "leading", "offset": [0.01, 0] }

Labels on the left, values on the right, both lined up however long they are:

{ "text": "CPU", "alignment": "leading", "offset": [-0.08, -0.015] },
{ "text": "{cpu}", "alignment": "trailing", "offset": [ 0.08, -0.015] },
{ "text": "MEMORY", "alignment": "leading", "offset": [-0.08, 0.015] },
{ "text": "{memory}", "alignment": "trailing", "offset": [ 0.08, 0.015] }

The World Clock and Day, Month and Year examples use this.

Draw a rounded rectangle first, then lay the contents out inside it:

{ "type": "shape", "shape": "rect", "size": [0.26, 0.15], "cornerRadius": 0.025, "fill": "#00000059", "shadow": false },
{ "text": "{weather.temperature}", "font": { "size": 0.06, "weight": "light" }, "alignment": "leading", "offset": [-0.11, 0] }

The card is 0.26 wide, so its left edge is at x = −0.13. Leading-aligned text at −0.11 leaves a 0.02 margin. See the Weather Card example for a complete card.

Elements with the same offset sit on top of each other, which is how you put text inside a ring:

{ "type": "progress", "style": "ring", "value": "{battery.level}", "size": [0.09, 0.09] },
{ "text": "{battery}", "font": { "size": 0.02, "weight": "semibold" } }
  • Start with the anchor. Decide which element people “hold” when they drag the widget and put it at [0, 0].
  • Work in round numbers. Offsets like 0.04, 0.06, 0.1 are easier to adjust than 0.0437.
  • Use the Size slider to check proportions. Everything scales together, so if it looks right at 1× it looks right at 2×.
  • Leave room for longer text. Weekdays, months and song titles vary a lot in width, and in other languages too. Test with Wednesday and September.
  • Hidden elements keep their space empty; other elements don’t move when one hides. Arrange optional elements so the gap doesn’t look odd.