# Deck

Deck puts Moor's widgets on your desktop, full size, over the wallpaper and under every window. They're the same widgets as in your docks. It stands in for macOS desktop widgets.

Turn it on in **Settings → Parts**. Deck needs no permissions. Everything below is in **Settings → Deck**, which appears while Deck is on. See [Turn parts on and off](/docs/parts/).

## Add widgets

Choose **Add Widget…** in Settings → Deck, in edit mode's toolbar, or **Deck → Add Widget to Desktop…** in the menu bar menu. A gallery opens with a preview of every widget, grouped like the docks' Add menu, and a search field. Click a widget to put it in the first free spot on the display the pointer is on, or drag it to where you want it on the desktop. Widgets that need an account or setup say so, as they do in a dock. See [Widgets](/docs/widgets/).

## Move and arrange

- **Drag.** Press and hold a widget for a moment, then drag it. In edit mode a drag starts at once. The widget follows the pointer, and an outline shows where it will land.
- **Snapping.** Near another widget, a widget lines up with its edges or sits beside it with an even gap. Near the edge of the display it keeps a margin. Elsewhere it snaps to an 8-point grid.
- **No overlaps.** A widget dropped on another one moves to the nearest free spot. Resizing and moving with the keyboard work the same way: an arrow-key step that would land on another widget is skipped.
- **Right-click** (or Control-click) a widget for **Size**, **Edit Widget…**, **Remove Widget** and **Edit Widgets**.

## Edit mode

Choose **Edit on Desktop** in Settings → Deck, **Edit Widgets** in a widget's right-click menu, or **Deck → Edit Desktop Widgets** in the menu bar menu. The widgets come up over your windows and a toolbar appears with **Add Widget…**, **Settings…** and **Done**.

- **Remove.** Click the **−** on the widget's top-left corner.
- **Resize, move to another display, settings.** Click the **…** on its top-right corner.
- **By keyboard.** Click a widget, then use the arrow keys to move it (hold <kbd>⇧</kbd> for bigger steps), <kbd>Delete</kbd> to remove it and <kbd>Esc</kbd> to finish. The selected widget has a solid outline and its name with "Selected" on its bottom edge.

Everything edit mode does is also in the **Widgets** list in Settings → Deck, with buttons and menus instead of dragging: each widget's size, which display it's on, arrows to move it, its own settings and **Remove**. Choose **Done** or press <kbd>Esc</kbd> to leave edit mode.

## Clicks

Outside edit mode, a widget that does something on click, such as play and pause in Now Playing, takes the click. Its details open in a small panel beside it. A click on a widget with nothing to click brings the desktop forward, as a click on the desktop does.

## Look

Each widget's glass is tinted for the wallpaper behind it, so its text stays readable on light and dark wallpapers. In Dark Mode widgets are dark. In Light Mode they're light on a light wallpaper and dark on a dark one. Deck reads the desktop picture file to do this; it doesn't record the screen.

**Dim widgets on desktop** (Settings → Deck → Appearance) works like the setting for Apple's widgets:

- **Automatically**: widgets turn monochrome and see-through while an app's window is in front on their display, and come back to full colour when you click the desktop.
- **Always**: always monochrome and see-through, except in edit mode.
- **Never**: always full colour.

With **Reduce Transparency** on (System Settings → Accessibility → Display), widgets, the toolbar and the gallery use a solid background instead of glass. With **Reduce Motion** on, widgets move and appear without animating.

## One layout per display

Each widget belongs to a display. Moor remembers it by that display, so a widget on your external monitor goes back there when you plug it in. While that display is away, its widgets show on your main display.

## A layout for each profile

By default every profile shows the same widgets. To give a profile its own, open Settings → Deck and turn on **Own desktop widgets for “Profile name”**. The profile starts from a copy of the shared widgets, which you can then change without touching the others. Turn it off to go back to the shared ones. This drops that profile's own widgets.

When you switch profiles, the desktop follows.

## When Deck hides

Deck follows **Show Widgets** in System Settings → Desktop & Dock. Turn off **On Desktop** and Deck's widgets hide too. If you use Stage Manager and turn off **In Stage Manager**, they hide while Stage Manager is on. Widgets also hide while an app is full screen on their display, and come back when it isn't. Edit mode always shows them.

Widgets are paused while the screen is asleep, your session is locked, or they're covered by other windows, so they don't use energy you can't see. Turn Deck off and every desktop widget window goes away.

Deck's widgets sit above desktop icons, so a widget can cover an icon. Move the widget, or the icon, if one is hidden.

## From agents

With Deck on, agents (the `moor_deck` MCP tool), scripts and the `moor` command can add, move, resize, set up and remove desktop widgets, and change dimming, edit mode and whether the active profile has its own widgets. They work on what the active profile shows. Moor must be running with **Settings → Automation → Let apps and agents control Moor** on.

```sh
moor deck widgets                 # every desktop widget, with its display and place, as JSON
moor deck edit on                 # edit mode; off to finish
moor api POST /v1/deck/widgets '{"kind": "calendar.nextEvent", "size": "wide", "x": 40, "y": 40}'
moor api PATCH /v1/deck/settings '{"dimming": "never"}'
```

Widgets land on the grid and never overlap, just as when you drag them. See [MCP server and local API](/docs/api/) for every route.

---
Source: https://moorapp.com/docs/deck/