# useScreen

> Tracks window.screen, refreshing it on every resize.

- Category: DOM
- Package: `hookli` (install with `npm i hookli`)
- Docs: https://hookli.vercel.app/docs/use-screen

## Signature

```ts
useScreen(options?: UseScreenOptions): Screen | null
```

## Parameters

- `options`: `UseScreenOptions` (default: `{}`) — Hydration behaviour. Optional.

## Returns

- `screen`: `Screen | null` — The current window.screen (width, height, availWidth, colorDepth, orientation…), refreshed on every resize. null on the server and until hydration.

## Types

### UseScreenOptions

Configures mount behaviour.

- `initializeWithValue`: `boolean` (default: `true`) — Read the real screen synchronously on mount. Set false to start as null and populate after hydration.

## Usage

```tsx
import { useScreen } from "hookli";

export function Demo() {
  const screen = useScreen();

  return <p>Screen: {screen ? `${screen.width}×${screen.height}` : "…"}</p>;
}
```

## Source

`src/hooks/use-screen/use-screen.ts`

```ts
import { useState } from "react";
import { useEventListener } from "../use-event-listener/use-event-listener";
import { useIsomorphicLayoutEffect } from "../use-isomorphic-layout-effect/use-isomorphic-layout-effect";

interface UseScreenOptions {
  initializeWithValue?: boolean;
}

const IS_SERVER = typeof window === "undefined";

export function useScreen(options: UseScreenOptions = {}): Screen | null {
  const { initializeWithValue = true } = options;

  const readScreen = (): Screen | null => {
    if (IS_SERVER) return null;
    return window.screen;
  };

  const [screen, setScreen] = useState<Screen | null>(() => {
    if (initializeWithValue) return readScreen();
    return null;
  });

  const handleSize = () => {
    setScreen(readScreen());
  };

  useEventListener("resize", handleSize);

  useIsomorphicLayoutEffect(() => {
    handleSize();
  }, []);

  return screen;
}
```