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

# usePrefersColorScheme

> Detects the user's system color scheme preference (light or dark mode).

## Usage

```tsx theme={null}
import { usePrefersColorScheme } from "@servicetitan/anvil2";

function ThemeAwareComponent() {
  const { mode } = usePrefersColorScheme();

  return (
    <div className={mode === "dark" ? "dark-theme" : "light-theme"}>
      System prefers: {mode} mode
    </div>
  );
}
```

## Return Value

| Property | Type                | Description                            |
| -------- | ------------------- | -------------------------------------- |
| `mode`   | `"light" \| "dark"` | Current system color scheme preference |

## Features

* Automatically updates when system preference changes
* Works with both modern and legacy browsers
* Handles SSR environments gracefully

## Examples

### Conditional Styling

```tsx theme={null}
function AdaptiveDiv() {
  const { mode } = usePrefersColorScheme();

  return (
    <div
      style={{
        backgroundColor: mode === "dark" ? "#1a1a1a" : "#ffffff",
        color: mode === "dark" ? "#ffffff" : "#000000",
      }}
    >
      This div adapts to system preferences
    </div>
  );
}
```

### With Theme Provider

```tsx theme={null}
function App() {
  const { mode } = usePrefersColorScheme();

  return (
    <ThemeProvider mode={mode}>
      <AppContent />
    </ThemeProvider>
  );
}
```

### Image Variants

```tsx theme={null}
function Logo() {
  const { mode } = usePrefersColorScheme();

  return (
    <img
      src={mode === "dark" ? "/logo-light.svg" : "/logo-dark.svg"}
      alt="Logo"
    />
  );
}
```

## Browser Support

The hook uses the `prefers-color-scheme` media query:

```tsx theme={null}
window.matchMedia("(prefers-color-scheme: dark)");
```

It supports both modern browsers (using `addEventListener`) and legacy browsers (using the deprecated `addListener` method).

## SSR Considerations

When running on the server (where `window` is undefined), the hook defaults to `"light"` mode. The actual system preference will be detected on the client after hydration.