EnvironmentValuesReader#

EnvironmentValuesReader is a Scripting component that allows you to read environment values from the current view hierarchy. It serves a similar role to SwiftUI’s @Environment, but with a more explicit and controlled design: You must specify which environment keys you want to read, and the component will inject only those values into the children callback.

This makes environment access predictable, explicit, and optimized.

EnvironmentValues Type#

1type EnvironmentValues = {
2    colorScheme: ColorScheme;
3    colorSchemeContrast: ColorSchemeContrast;
4    displayScale: number;
5    horizontalSizeClass: UserInterfaceSizeClass | null;
6    verticalSizeClass: UserInterfaceSizeClass | null;
7    dismiss: () => void;
8    dismissSearch: () => void;
9    editMode: EditMode | null;
10    widgetRenderingMode: WidgetRenderingMode;
11    showsWidgetContainerBackground: boolean;
12    isSearching: boolean;
13    isPresented: boolean;
14};

Below are the descriptions of each field.

Field Descriptions#

1. colorScheme#

Type: ColorScheme The current system color appearance (light or dark).

2. colorSchemeContrast#

Type: ColorSchemeContrast Represents contrast settings such as standard or increased.

3. displayScale#

Type: number The display scale factor of the device (e.g., 2.0, 3.0).

4. horizontalSizeClass#

Type: UserInterfaceSizeClass | null The horizontal size class of the current environment: compact or regular.

5. verticalSizeClass#

Type: UserInterfaceSizeClass | null The vertical size class, same categories as above.

6. dismiss#

Type: () => void A function to dismiss the currently presented view (equivalent to SwiftUI’s dismiss()).

7. dismissSearch#

Type: () => void A function that dismisses the current searchable field, if active.

8. editMode#

Type: EditMode | null Indicates whether the view is in editing mode (e.g., during List editing).

9. widgetRenderingMode#

Type: WidgetRenderingMode The current widget rendering mode (e.g., fullColor, accented).

10. showsWidgetContainerBackground#

Type: boolean Indicates whether the widget is showing the system-provided container background.

11. isSearching#

Type: boolean Whether the view is currently in a searching state triggered by searchable.

12. isPresented#

Type: boolean Whether the view is currently being shown, unlike onAppear which is called every time the view appears, isPresented is called only once when the view is first shown.

EnvironmentValuesReader Component#

1type EnvironmentValuesReaderProps = {
2    /**
3     * The keys to read from the environment values.
4     */
5    keys: Array<keyof EnvironmentValues>;
6    /**
7     * The callback function that receives the environment values.
8     */
9    children: (values: EnvironmentValues) => VirtualNode;
10};

Props Description#

keys#

Type: Array<keyof EnvironmentValues> Specifies exactly which environment keys you want to read. Only these keys will be retrieved and passed to the callback.

children(values)#

Type: (values: EnvironmentValues) => VirtualNode A rendering callback that receives the requested environment values and returns the corresponding view.

Component Definition#

1declare const EnvironmentValuesReader: FunctionComponent<EnvironmentValuesReaderProps>;

Usage Examples#

Example 1 — Reading colorScheme and displayScale#

1import { EnvironmentValuesReader, Text, VStack } from "scripting"
2
3function View() {
4  return <EnvironmentValuesReader keys={["colorScheme", "displayScale"]}>
5    {(env) => {
6      return <VStack>
7        <Text>Color Scheme: {env.colorScheme}</Text>
8        <Text>Scale: {env.displayScale}</Text>
9      </VStack>
10    }}
11  </EnvironmentValuesReader>
12}

Example 2 — Accessing dismiss#

1<EnvironmentValuesReader keys={["dismiss"]}>
2  {(env) => {
3    return <Button
4      title="Close"
5      action={() => env.dismiss()}
6    />
7  }}
8</EnvironmentValuesReader>

Example 3 — Dynamic layout using size classes#

1<EnvironmentValuesReader keys={["horizontalSizeClass"]}>
2  {(env) => {
3    const compact = env.horizontalSizeClass === "compact"
4    return compact
5      ? <Text>Compact Layout</Text>
6      : <Text>Regular Layout</Text>
7  }}
8</EnvironmentValuesReader>

Behavior Notes#

1. Only the explicitly listed keys are read. All other environment values will not be included in the callback.
2. When any of the requested environment values change, the children() callback re-renders automatically.
3. dismiss and dismissSearch are real functional operations that behave like their SwiftUI equivalents.
4. Environment values originate from the parent view hierarchy (Navigation, searchable, editMode, Widget context, etc.).
5. If a key is not included in keys, it will not appear in the values object.
6. This API is not intended for global state management—only for accessing the contextual environment of the current view.