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

# Web reader player appearance

> Set the web reader player's widget language, theme, accent colour, layout, size and alignment, custom CSS and launcher label, with each default and the preview.

> [!NOTE]
>
> Web reader is in beta and switched on for selected accounts.

The **Appearance** and **Floating launcher** cards on a site's **Settings** tab decide how the player looks on your articles. Every change shows in the preview at the top of the card first, and reaches your site when you click **Save changes**. Readings and voices are on [Set up a site](https://docs.tryhamsa.com/media/web-reader/set-up-a-site.md#readings-and-voices).

![The Appearance card: the player preview, Widget language, Theme set to Dark and the lime accent colour](https://mintcdn.com/hamsa-452fa79a/SjdNHyLOJ-5kYaqE/images/media/web-reader/appearance-light.webp?fit=max\&auto=format\&n=SjdNHyLOJ-5kYaqE\&q=85\&s=2b5498ca3ec92b26604447a60f4e73e8)

## Settings and defaults

| Setting | What it does | Default |
| - | - | - |
| **Widget language** | The language of the player's own controls and button wording: **Arabic** or **English**. Arabic also lays the player out right to left. It doesn't change which reading plays. | The language of the site's first voice |
| **Theme** | **Dark** or **Light** is a designed colour set for the player and the launcher. **Custom** lets you pick **Background** and **Text** yourself. | **Dark** |
| **Accent colour** | The play button, progress and highlights. **Reset** brings back the default. | `#97DE00` (Hamsa lime) |
| **Custom CSS** | Your own CSS for the player, up to 10,000 characters. | Empty |
| **Layout** | The player's shape: **Default**, **Compact**, **Minimal**, **Floating** or **Expanded**. | **Default** |
| **Player size** | **Width**, **Maximum width**, **Height**, **Minimum height** and **Alignment**. | **Full width**, **Auto** height, **Centre** |
| **Button label** | The wording on the floating launcher, up to 40 characters. | "Listen to Article" |

Under the colours, a contrast note says whether text on the background and text on the accent are readable ("Readable contrast (WCAG AA)"), or warns when one is below what WCAG AA asks for.

![Theme set to Custom, with Accent colour, Background and Text fields and the contrast note](https://mintcdn.com/hamsa-452fa79a/SjdNHyLOJ-5kYaqE/images/media/web-reader/custom-theme-light.webp?fit=max\&auto=format\&n=SjdNHyLOJ-5kYaqE\&q=85\&s=1e2b6a18f32e4e674947d230888f2bd3)

Theme, colours, accent, widget language and button label travel in the snippet. After saving them, copy the snippet again from **Setup** and replace it on your site.

## Layouts

| Layout | What it looks like |
| - | - |
| **Default** | The standard player, with balanced padding and every control. |
| **Compact** | Less padding and tighter spacing, for short spaces: smaller play button and title, thinner progress bar. |
| **Minimal** | Few borders, just the playback essentials: no border and no shadow. |
| **Floating** | A raised card with a soft shadow and rounded corners, like a capsule over the page. |
| **Expanded** | Roomier, with a larger play button and title, generous padding and a divider above the progress bar. On narrow screens (under about 420 pixels) it falls back to default sizes. |

The **Floating** layout is a look. Whether the player sits in the article or in a corner of the screen is decided by how the snippet is installed. See [Inline or floating](https://docs.tryhamsa.com/media/web-reader/add-to-your-site.md#inline-or-floating).

![The Layout choices and the Player size fields: Width, Maximum width, Height, Minimum height and Alignment](https://mintcdn.com/hamsa-452fa79a/SjdNHyLOJ-5kYaqE/images/media/web-reader/layout-size-light.webp?fit=max\&auto=format\&n=SjdNHyLOJ-5kYaqE\&q=85\&s=0c7e0181e219e88564e52a0b7021a406)

## Player size

| Field | Options | Range |
| - | - | - |
| **Width** | **Auto** fits the content, **Full width** fills the space it is placed in, **Fixed** sets pixels | Fixed: 200 to 2,000 px, starts at 600 |
| **Maximum width** | Optional cap; the player stays responsive on smaller screens | 200 to 3,000 px |
| **Height** | **Auto** or **Fixed** | Fixed: 50 to 800 px, starts at 100 |
| **Minimum height** | Optional | 40 to 500 px |
| **Alignment** | **Left**, **Centre** or **Right** | |

A fixed width never grows past the space the player is in.

## Custom CSS

Use **Custom CSS** to restyle the player beyond the settings above.

**1. Start from a preset (optional)**

Click a preset: **Glass**, **Sharp**, **Outline** or **Compact**. It replaces what is in the box.

**2. Write your rules**

Target `.wr-card` or set the `--wr-*` variables. Click **Show variables** for the full list of variables and classes.

**3. Check the preview and save**

The preview shows the result. Click **Save changes**.

![The Custom CSS field with the Glass preset applied, the four presets and Show variables](https://mintcdn.com/hamsa-452fa79a/SjdNHyLOJ-5kYaqE/images/media/web-reader/custom-css-light.webp?fit=max\&auto=format\&n=SjdNHyLOJ-5kYaqE\&q=85\&s=7be838e505381cff3a48dd3786e58091)

```css theme={null}
.wr-card {
  --wr-radius: 8px;
  --wr-backdrop: blur(12px);
}
.wr-play {
  --wr-play-size: 44px;
}
```

| Variables | Classes |
| - | - |
| `--wr-radius`, `--wr-radius-control`, `--wr-padding`, `--wr-play-size`, `--wr-border-width`, `--wr-track-height`, `--wr-title-size`, `--wr-backdrop`, `--wr-surface`, `--wr-surface-2`, `--wr-border`, `--wr-text`, `--wr-accent`, `--wr-track`, `--wr-shadow`, `--wr-sans`, `--wr-display` | `.wr-card`, `.wr-play`, `.wr-title`, `.wr-meta`, `.wr-controls`, `.wr-speed`, `.wr-lang`, `.wr-mute`, `.wr-download`, `.wr-close`, `.wr-progress-row`, `.wr-progress`, `.wr-time`, `.wr-eq` |

You can also match the player's state with `[data-state="ready"]` (or `loading`, `processing`, `error`), `[data-playing="true"]`, and `[data-layout="compact"]` (or any layout name).

### Which rule wins

* Custom CSS always wins over the layouts: a layout only sets starting values for the same variables, so your `--wr-radius` or `--wr-shadow` applies in every layout.
* Custom CSS also wins over the theme and custom colours, for example `--wr-surface` and `--wr-text`.
* CSS set on one page with `data-custom-css` wins over the CSS saved on the site. See [Override on one page](https://docs.tryhamsa.com/media/web-reader/add-to-your-site.md#override-settings-on-one-page).

### What is removed

Rules only apply inside the player. Before your CSS is used, Hamsa removes anything that loads a file or runs code: `@import`, `@font-face`, `url()` to anything except inline `data:image` images, and old script tricks. Rules that target the "Voiced by Hamsa" mark are dropped, and the mark always stays visible.

## Floating launcher

When the snippet is installed with floating placement, readers first see a small button in the corner of the page. The **Floating launcher** card sets its **Button label** and shows a preview. The launcher takes its colours from the theme and accent. With inline placement there is no launcher, and this setting has no effect.

![The Floating launcher card with a preview of the Listen to Article button and the Button label field](https://mintcdn.com/hamsa-452fa79a/SjdNHyLOJ-5kYaqE/images/media/web-reader/floating-launcher-light.webp?fit=max\&auto=format\&n=SjdNHyLOJ-5kYaqE\&q=85\&s=d6c3d1f81748f9af27cf87da9ba37189)

## Good to know

* The **Widget language** and the reading are separate. An Arabic news site can offer an English reading and still show Arabic controls.
* On a page that reads right to left, the floating launcher sits in the bottom left corner instead of the bottom right.
* Readers can change speed (1x, 1.25x, 1.5x, 2x, 0.75x), mute, switch reading when you offer several, and download the audio.

## Related

> [card] [Add the player to your site](https://docs.tryhamsa.com/media/web-reader/add-to-your-site.md)
>
> Inline or floating, and per-page overrides.

> [card] [Set up a site](https://docs.tryhamsa.com/media/web-reader/set-up-a-site.md)
>
> Readings, voices and dictionaries.


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