> ## 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

Which keys are set depends on the renderer. iOS sets `colorScheme`, `displayScale`, `dynamicTypeSize`, `layoutDirection`, and `locale`. Web sets `colorScheme`, `platform`, and `screen`. The Android renderer (bindjs-android 0.0.33) sets none of them. Read each with a fallback.

An `EnvironmentValues` object with the following fields:

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

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

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

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

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

<ParamField path="screen" type="{ width: number; height: number }" optional>
  Screen dimensions in points. Not set by every renderer.
</ParamField>

<ParamField path="platform" type="string" optional>
  The current platform. The web renderer sets it to `"web"`.
</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 || 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


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