> ## Documentation Index
> Fetch the complete documentation index at: https://recircles.rekosk.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Launcher configuration

> Locate recircles.json, arrange your main ring, choose what happens when it fills up, and adjust animation, contrast, blur, or transparency in the launcher.

ReCircles creates `recircles.json` with defaults on first launch. Run `recircles --run settings` to edit it visually. Settings changes apply live and save automatically. For hand edits, close the launcher, save the JSON, and reopen it.

## Where files belong

| Path under the configuration directory | Contents |
| - | - |
| `recircles.json` | Main-ring entries, appearance, active colors, and keybindings. |
| `<menu-id>.json` | An installed custom menu. Open it with `recircles --run <menu-id>`. |
| `themes/<theme-id>.json` | A reusable palette listed in **Settings → Colors → Theme**. |

The usual directory is `~/.config/recircles`. When `XDG_CONFIG_HOME` is set to an absolute path, ReCircles uses its `recircles` subdirectory.

## Main-ring entries

`main_menu` is an ordered array. The default order is `files`, `apps`, `windows`, `wifi`, `bluetooth`, `settings`. Every entry requires a `name`. Optional `label` and `icon` fields override the displayed title and icon. A custom menu’s label falls back to its `title`, then its ID.

This example gives the ring three entries. Install [Places](https://recircles.rekosk.dev/docs/menus/create.md) first, then replace only the `main_menu` array in your configuration. The other built-in modes remain available through `--run`.

```json theme={null}
{
  "main_menu": [
    { "name": "files", "label": "Browse" },
    { "name": "places", "icon": "folder" },
    { "name": "settings" }
  ]
}
```

If a pinned custom menu file is missing, ReCircles removes its entry when reading the configuration. To restore the pin after reinstalling the file, run `recircles add places --main-menu folder`.

## Appearance

Set these fields inside `appearance`. Omitted settings use the defaults below.

| Key | Default | Effect |
| - | - | - |
| `overflow_layout` | `"box"` | With nine or more ring items, use a four-column grid showing up to three rows. Set `"rings"` for pages of up to eight sectors. |
| `animations` | `true` | Animate transitions when GTK animations are enabled. Set `false` for immediate layout changes. |
| `animation_3d` | `true` | Use a spinning 3D loading ring. Set `false` for a pulsing 2D ring. Aliases are `3d_animation`, `three_d_animation`, and `loading_3d`. |
| `translucent` | `true` | Allow the desktop to show through the launcher surfaces. |
| `blur` | `true` | Request compositor blur behind translucent surfaces when supported. |
| `high_contrast` | `false` | Increase rim contrast and make surfaces opaque. GTK HighContrast also enables this behavior. |

For example, this keeps large menus circular and makes transitions immediate.

```json theme={null}
{
  "appearance": {
    "overflow_layout": "rings",
    "animations": false
  }
}
```

The other top-level objects control [palette colors](https://recircles.rekosk.dev/docs/themes/palette.md) and [keybindings](https://recircles.rekosk.dev/docs/reference/keybinds.md).

## Environment variables

| Variable | Use |
| - | - |
| `XDG_CONFIG_HOME` | Absolute base directory for configuration. Defaults to `$HOME/.config`. |
| `XDG_STATE_HOME` | Absolute base directory for usage history. Defaults to `$HOME/.local/state`. Counts are stored in `recircles/usage` below it. |
| `RECIRCLES_REDUCED_MOTION` | Set for a launch to disable animation. |
| `RECIRCLES_REDUCED_TRANSPARENCY` | Set for a launch to make surfaces opaque. |
| `RECIRCLES_INPUT` | Set by ReCircles for a menu command that receives a value. Read it as `"$RECIRCLES_INPUT"` in the shell. |

The two reduced-effects switches check for the presence of the variable. Unset a switch to return control to your appearance and desktop settings.

```sh theme={null}
RECIRCLES_REDUCED_MOTION=1 recircles --run apps
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.