# Placeholder Usage

## PlaceholderAPI Placeholders

KeyAllz provides several [PlaceholderAPI](https://github.com/PlaceholderAPI/PlaceholderAPI) placeholders for displaying timer information in chat, scoreboards, GUIs, or plugins.

Each placeholder requires the **timer name** (as defined in `/keyallz start <definition>`) to be specified.

***

### `%keyallz_timer_<name>%`

**Displays:** Full remaining time.\
**Format:** `1d 2h 10m 5s`

**Example**

```
%keyallz_timer_workout%
→ 0d 0h 25m 10s
```

***

### `%keyallz_days_<name>%`

**Displays:** Remaining **days** as an integer.

**Example**

```
%keyallz_days_event%
→ 3
```

***

### `%keyallz_hours_<name>%`

**Displays:** Remaining **hours** as an integer.

**Example**

```
%keyallz_hours_stream%
→ 5
```

***

### `%keyallz_minutes_<name>%`

**Displays:** Remaining **minutes** as an integer.

**Example**

```
%keyallz_minutes_break%
→ 15
```

***

### `%keyallz_secs_<name>%` or `%keyallz_seconds_<name>%`

**Displays:** Remaining **seconds** (short or full alias).

**Example**

```
%keyallz_secs_game%
→ 42
```

***

### `%keyallz_time_short_<name>%`

**Displays:** Compact time format.\
**Format:** `HH:mm:ss`

**Example**

```
%keyallz_time_short_workout%
→ 00:25:10
```

***

### `%keyallz_remaining_<name>%`

**Displays:** Condensed remaining time.\
**Format:** Automatically shortens based on duration — e.g. `10m 30s`, `1h 5m`, etc.

**Example**

```
%keyallz_remaining_meditation%
→ 8m 45s
```

***

#### Notes

* `<name>` must match an active timer definition.
* If the timer is not active, the placeholder will return an empty or default value.
* Short formats automatically omit zero-value units.

***