---
id: "packages/active-ui/full-screen"
title: "FullScreen"
description: "An icon button that puts the whole page, or one element, in full screen and back, named after where a click leads."
url: "/packages/active-ui/full-screen"
locale: "en"
revision: "8dc60d9392949f1f"
---

# FullScreen

`FullScreen` is the full-screen button of an application header. Pressing it asks the browser to
show the page in full screen; pressing it again, or `Escape`, leaves full screen. Its name and icon
follow the state.

**Example: The full-screen button**

Client: Runs entirely in your browser. Source: `examples/ui/full-screen.tsx`.

```tsx
// apps/docs/examples/ui/full-screen.tsx
'use client';

import {FullScreen} from '@workspace/active-ui/components/composed/full-screen';
import {TooltipProvider} from '@workspace/active-ui/components/primitives/tooltip';

/**
 * The full-screen button of an application header. It puts the whole page in
 * full screen; `Escape` or the button bring it back, and the button's name
 * follows. With `showTooltip` its name is also shown as a tooltip.
 */
export default function FullScreenExample() {
  return (
    <TooltipProvider>
      <FullScreen
        enterLabel="Full screen"
        exitLabel="Standard screen"
        showTooltip
      />
    </TooltipProvider>
  );
}
```

## What the composition adds

- **A state that follows the browser**: it listens to `fullscreenchange`, so leaving full screen
  with `Escape` changes the button too. When the browser refuses, nothing changes.
- **Two names**, `enterLabel` and `exitLabel`, both naming where a click leads.
- **`showTooltip`** shows the current name as a tooltip, the same word as the accessible name. Put
  a `TooltipProvider` above it to set the delay.
- **`target`**: a ref to one element (an example, a chart, a map) to show that element in full
  screen instead of the page. The button then follows only that element.

## Usage

```tsx
import {FullScreen} from '@workspace/active-ui/components/composed/full-screen';

<FullScreen enterLabel="Full screen" exitLabel="Standard screen" showTooltip />;
```

## What your application provides

- Both names, translated and short.
- A page that may use full screen: a frame without the `fullscreen` permission refuses it.

## API

| Prop | Type | Required | Description |
| --- | --- | --- | --- |
| `enterLabel` | `string` | yes | Accessible name of the button when the screen is **not** full screen: "Full screen".  Required, and supplied translated. Never hard-code a string here: the icon carries no text, so this is the only name the button has, and `active-ui` does not translate.  Keep it short. This is a name tag, not an instruction: the button sits in a row of five, and a full sentence per button turns a row of tooltips into a reading exercise. |
| `exitLabel` | `string` | yes | Accessible name when in full screen: "Standard screen".  Names the **destination**, not the action, just like {@link enterLabel}: both say where a click leads. A command ("close full screen") breaks that pattern, because its counterpart points at a place. |
| `className` | `string` | no | Classes for the button. |
| `showTooltip` | `boolean` | no | Also shows the accessible name as a tooltip.  **A flag and not a text**, because the name changes with the button's state: a passed-in string would keep saying "open" once the screen is full screen. This way tooltip and `aria-label` always show the same word, which is also the intent of WCAG 2.5.3 (label in name).  **Off by default.** The open delay lives on `Tooltip.Provider`, so a tooltip that enabled itself would open after 300ms in one tree and immediately in another, depending on whether a provider happens to sit above it. A caller that wants a tooltip provides the provider. |
| `target` | `RefObject<HTMLElement \| null>` | no | The element to show full screen; without it, the whole page. With a target, the button reflects only that element: another element in full screen leaves it on {@link enterLabel}. |

**FullScreenProps**

```ts
interface FullScreenProps {
  enterLabel: string;
  exitLabel: string;
  showTooltip?: boolean;
  className?: string;
  target?: React.RefObject<HTMLElement | null>;
}
```