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

# useEnvironment

> Reads the current environment values including color scheme, locale, screen size, and custom values.

```typescript theme={null}
useEnvironment(): EnvironmentValues;
```

## Returns

An `EnvironmentValues` object with the following fields:

<ParamField path="colorScheme" type="&#x22;light&#x22; | &#x22;dark&#x22;">
  The current appearance mode.
</ParamField>

<ParamField path="displayScale" type="number">
  The display pixel density (e.g. 2.0 for Retina displays).
</ParamField>

<ParamField path="dynamicTypeSize" type="DynamicTypeSize">
  The user's preferred text size setting. See [DynamicTypeSize](/bindjs/types/DynamicTypeSize).
</ParamField>

<ParamField path="locale" type="string">
  The current locale identifier (e.g. `"en_US"`).
</ParamField>

<ParamField path="layoutDirection" type="&#x22;leftToRight&#x22; | &#x22;rightToLeft&#x22;">
  Text layout direction.
</ParamField>

<ParamField path="screen" type="{ width: number; height: number }">
  Screen dimensions in points.
</ParamField>

<ParamField path="platform" type="string" optional>
  The current platform (e.g. `"iOS"`, `"web"`, `"android"`).
</ParamField>

<ParamField path="openURL" type="(url: string, resultCallback?: (success: boolean) => void) => void">
  Opens a URL using the platform's default handler.
</ParamField>

Custom environment values set via the `.environment()` modifier are also available as additional properties on the returned object.

## Usage

### Adapt to color scheme

```typescript theme={null}
const body = () => {
    const env = useEnvironment()
    const isDark = env.colorScheme === "dark"

    return Text("Current theme: " + (isDark ? "Dark" : "Light"))
        .foregroundStyle(Color(isDark ? "white" : "black"))
}
```

### Responsive layout

```typescript theme={null}
const body = () => {
    const env = useEnvironment()
    const isCompact = env.screen.width < 400

    return isCompact
        ? VStack({ spacing: 8 }, [
            Text("Title").font("headline"),
            Text("Subtitle").font("subheadline")
        ])
        : HStack({ spacing: 16 }, [
            Text("Title").font("headline"),
            Text("Subtitle").font("subheadline")
        ])
}
```

### Read custom environment values

```typescript theme={null}
const body = () => {
    const env = useEnvironment()
    const accentColor = env.accentColor || "blue"

    return Text("Styled text")
        .foregroundStyle(Color(accentColor))
}
```

### Open a URL

```typescript theme={null}
const body = () => {
    const env = useEnvironment()

    return Button("Visit Website", () => {
        env.openURL("https://example.com")
    })
}
```

## Notes

* `useEnvironment` must be called inside a component `body` function, not at the top level.
* Custom values are set via the `.environment()` modifier on a parent component, e.g. `.environment("accentColor", "purple")`.
* The `screen` dimensions are in logical points, not physical pixels.

## See Also

* [OpenURLAction](/bindjs/functions/OpenURLAction) -- custom URL handling