# Clock card

> The clock card shows the current time, as a digital or an analog clock, with an optional date.

Source: https://contributors.home-assistant.io/design/dashboards/clock-card/

Live demo of `hui-card`, connected to a demo Home Assistant.

```html
<hui-card style="width: 340px" data-props='{"config": {"type": "clock", "clock_size": "large", "date_format": ["weekday-long", "day-numeric", "month-long"]}}'></hui-card>
<hui-card style="width: 200px" data-props='{"config": {"type": "clock", "clock_style": "analog", "clock_size": "medium"}}'></hui-card>
```

## Usage

The clock card shows the time. It is made for dashboards that stay on screen, like a wall tablet in the hallway or a screen in the kitchen, where the time is one of the first things people look for.

On a dashboard that people open on their phone, leave it out. The phone already shows the time, and the card takes room from the things they came for.

The time follows the time format of the user, 12 or 24 hours, and the time zone set in their profile. It ticks every second, so it is always right.

### Digital or analog

The default is a digital clock. With `clock_style: analog`, the card shows a clock face with hands. A digital clock is quicker to read from a distance. An analog clock fits a calmer, more decorative dashboard. Pick one style and use it everywhere on the dashboard.

Live demo of `hui-card`, connected to a demo Home Assistant.

```html
<hui-card style="width: 200px" data-props='{"config": {"type": "clock", "clock_style": "analog", "clock_size": "medium", "face_style": "numbers_upright", "border": true, "show_seconds": true}}'></hui-card>
<hui-card style="width: 200px" data-props='{"config": {"type": "clock", "clock_style": "analog", "clock_size": "medium", "ticks": "minute"}}'></hui-card>
```

An analog clock has its own options: `face_style` shows markers, numbers, or Roman numerals, `ticks` sets how many tick marks the face has, and `border` draws a circle around it.

### Size

`clock_size` makes the clock `small`, `medium`, or `large`. The card grows with it in the sections view. Use the large size when the clock is the main thing on the screen, and the small one when it sits in a corner.

Live demo of `hui-card`, connected to a demo Home Assistant.

```html
<hui-card style="width: 340px" data-props='{"config": {"type": "clock"}}'></hui-card>
<hui-card style="width: 340px" data-props='{"config": {"type": "clock", "clock_size": "medium"}}'></hui-card>
```

### Date and title

`date_format` adds the date below the time. It is a list of parts, like the day of the week, the day, and the month, so it can follow any local order. `title` adds a line of text above the time, like the name of a city when the card shows another time zone.

Live demo of `hui-card`, connected to a demo Home Assistant.

```html
<hui-card style="width: 340px" data-props='{"config": {"type": "clock", "title": "Tokyo", "time_zone": "Asia/Tokyo", "clock_size": "medium"}}'></hui-card>
```

### No background

With `no_background: true`, the clock has no card around it, and sits on the dashboard itself. It looks good on a dashboard with a background picture.

## Configuration

- `clock_style` (string): `digital` or `analog`. Defaults to `digital`.
- `clock_size` (string): `small`, `medium`, or `large`. Defaults to `small`.
- `title` (string): a line of text above the clock.
- `show_seconds` (boolean): shows the seconds, or a second hand on an analog clock. Defaults to `false`.
- `time_format` (string): `12` or `24` hours, `language` to follow the language, or `system` to follow the device. Defaults to the time format of the user. Digital clock only.
- `time_zone` (string): the time zone to show the time of, like `Asia/Tokyo`. Defaults to the time zone of the user.
- `date_format` (list): the parts of the date to show, like `weekday-short`, `day-numeric`, `month-long`, `year-numeric`, or a separator.
- `no_background` (boolean): shows the clock without the card background. Defaults to `false`.
- `face_style` (string): `markers`, `numbers_upright`, or `roman`. Defaults to `markers`. Analog clock only.
- `ticks` (string): `none`, `quarter`, `hour`, or `minute`. Defaults to `hour`. Analog clock only.
- `border` (boolean): draws a circle around the face. Defaults to `false`. Analog clock only.
- `seconds_motion` (string): `continuous` or `tick`, how the second hand moves. Defaults to `continuous`. Analog clock only.

```yaml
type: clock
clock_size: large
date_format:
  - weekday-long
  - day-numeric
  - month-long
```

## In code

The card lives in [`src/panels/lovelace/cards/hui-clock-card.ts`](https://github.com/home-assistant/frontend/blob/dev/src/panels/lovelace/cards/hui-clock-card.ts), and the element is `<hui-clock-card>`. It loads one of two elements for the clock itself, from [`src/panels/lovelace/cards/clock/`](https://github.com/home-assistant/frontend/tree/dev/src/panels/lovelace/cards/clock): `<hui-clock-card-digital>` or `<hui-clock-card-analog>`. The date parts and how they are formatted live in `clock-date-format.ts` in the same folder.

In the sections view, the clock takes 6 columns. A small digital clock takes 1 row, and grows with its size and its title. An analog clock needs at least 2 rows.

[Source](https://github.com/home-assistant/frontend/blob/dev/src/panels/lovelace/cards/hui-clock-card.ts)