<!--
{
  "availability" : [
    "iOS: 13.0.0 -",
    "iPadOS: 13.0.0 -",
    "macCatalyst: 13.0.0 -",
    "macOS: 10.15.0 -",
    "tvOS: 13.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 6.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "SwiftUI",
  "identifier" : "/documentation/SwiftUI/EnvironmentValues",
  "metadataVersion" : "0.1.0",
  "role" : "Structure",
  "symbol" : {
    "kind" : "Structure",
    "modules" : [
      "SwiftUI"
    ],
    "preciseIdentifier" : "s:7SwiftUI17EnvironmentValuesV"
  },
  "title" : "EnvironmentValues"
}
-->

# EnvironmentValues

A collection of environment values propagated through a view hierarchy.

```
struct EnvironmentValues
```

## Overview

SwiftUI exposes a collection of values to your app’s views in an
`EnvironmentValues` structure. To read a value from the structure,
declare a property using the [`Environment`](/documentation/SwiftUI/Environment) property wrapper and
specify the value’s key path. For example, you can read the current locale:

```
@Environment(\.locale) var locale: Locale
```

Use the property you declare to dynamically control a view’s layout.
SwiftUI automatically sets or updates many environment values, like
[`pixelLength`](/documentation/SwiftUI/EnvironmentValues/pixelLength), [`scenePhase`](/documentation/SwiftUI/EnvironmentValues/scenePhase), or
[`locale`](/documentation/SwiftUI/EnvironmentValues/locale), based on device characteristics, system state,
or user settings. For others, like [`lineLimit`](/documentation/SwiftUI/EnvironmentValues/lineLimit), SwiftUI
provides a reasonable default value.

You can set or override some values using the [`environment(_:_:)`](/documentation/SwiftUI/View/environment(_:_:))
view modifier:

```
MyView()
    .environment(\.lineLimit, 2)
```

The value that you set affects the environment for the view that you modify
— including its descendants in the view hierarchy — but only up to the
point where you apply a different environment modifier.

SwiftUI provides dedicated view modifiers for setting some values, which
typically makes your code easier to read. For example, rather than setting
the [`lineLimit`](/documentation/SwiftUI/EnvironmentValues/lineLimit) value directly, as in the previous
example, you should instead use the [`lineLimit(_:)`](/documentation/SwiftUI/View/lineLimit(_:)) modifier:

```
MyView()
    .lineLimit(2)
```

In some cases, using a dedicated view modifier provides additional
functionality. For example, you must use the
[`preferredColorScheme(_:)`](/documentation/SwiftUI/View/preferredColorScheme(_:)) modifier rather than setting
[`colorScheme`](/documentation/SwiftUI/EnvironmentValues/colorScheme) directly to ensure that the new
value propagates up to the presenting container when presenting a view
like a popover:

```
MyView()
    .popover(isPresented: $isPopped) {
        PopoverContent()
            .preferredColorScheme(.dark)
    }
```

Create a custom environment value by declaring a new property
in an extension to the environment values structure and applying
the [`Entry()`](/documentation/SwiftUI/Entry()) macro to the variable declaration:

```
extension EnvironmentValues {
    @Entry var myCustomValue: String = "Default value"
}

extension View {
    func myCustomValue(_ myCustomValue: String) -> some View {
        environment(\.myCustomValue, myCustomValue)
    }
}
```

Clients of your value then access the value in the usual way, reading it
with the [`Environment`](/documentation/SwiftUI/Environment) property wrapper, and setting it with the
`myCustomValue` view modifier.

## Topics

### Creating and accessing values

[`init()`](/documentation/SwiftUI/EnvironmentValues/init())

Creates an environment values instance.

[`subscript(_:)`](/documentation/SwiftUI/EnvironmentValues/subscript(_:))

Accesses the environment value associated with a custom key.

[`description`](/documentation/SwiftUI/EnvironmentValues/description)

A string that represents the contents of the environment values
instance.

### Accessibility

[`accessibilityAssistiveAccessEnabled`](/documentation/SwiftUI/EnvironmentValues/accessibilityAssistiveAccessEnabled)

A Boolean value that indicates whether Assistive Access is in use.

[`accessibilityDimFlashingLights`](/documentation/SwiftUI/EnvironmentValues/accessibilityDimFlashingLights)

Whether the setting to reduce flashing or strobing lights in video
content is on. This setting can also be used to determine if UI in
playback controls should be shown to indicate upcoming content that
includes flashing or strobing lights.

[`accessibilityDifferentiateWithoutColor`](/documentation/SwiftUI/EnvironmentValues/accessibilityDifferentiateWithoutColor)

Whether the system preference for Differentiate without Color is enabled.

[`accessibilityEnabled`](/documentation/SwiftUI/EnvironmentValues/accessibilityEnabled)

A Boolean value that indicates whether the user has enabled an assistive
technology.

[`accessibilityInvertColors`](/documentation/SwiftUI/EnvironmentValues/accessibilityInvertColors)

Whether the system preference for Invert Colors is enabled.

[`accessibilityLargeContentViewerEnabled`](/documentation/SwiftUI/EnvironmentValues/accessibilityLargeContentViewerEnabled)

Whether the Large Content Viewer is enabled.

[`accessibilityPlayAnimatedImages`](/documentation/SwiftUI/EnvironmentValues/accessibilityPlayAnimatedImages)

Whether the setting for playing animations in an animated image is
on. When this value is false, any presented image that contains
animation should not play automatically.

[`accessibilityPrefersHeadAnchorAlternative`](/documentation/SwiftUI/EnvironmentValues/accessibilityPrefersHeadAnchorAlternative)

Whether the system setting to prefer alternatives to head-anchored
content is on.

[`accessibilityPrefersCrossFadeTransitions`](/documentation/SwiftUI/EnvironmentValues/accessibilityPrefersCrossFadeTransitions)

A Boolean value that indicates whether the Reduce Motion and the Prefer
Cross-Fade Transitions settings are in an enabled state.

[`accessibilityQuickActionsEnabled`](/documentation/SwiftUI/EnvironmentValues/accessibilityQuickActionsEnabled)

A Boolean that indicates whether the quick actions feature is enabled.

[`accessibilityReduceMotion`](/documentation/SwiftUI/EnvironmentValues/accessibilityReduceMotion)

Whether the system preference for Reduce Motion is enabled.

[`accessibilityReduceTransparency`](/documentation/SwiftUI/EnvironmentValues/accessibilityReduceTransparency)

Whether the system preference for Reduce Transparency is enabled.

[`accessibilityShowButtonShapes`](/documentation/SwiftUI/EnvironmentValues/accessibilityShowButtonShapes)

Whether the system preference for Show Button Shapes is enabled.

[`accessibilitySwitchControlEnabled`](/documentation/SwiftUI/EnvironmentValues/accessibilitySwitchControlEnabled)

A Boolean value that indicates whether the Switch Control motor
accessibility feature is in use.

[`accessibilityVoiceOverEnabled`](/documentation/SwiftUI/EnvironmentValues/accessibilityVoiceOverEnabled)

A Boolean value that indicates whether the VoiceOver screen reader
is in use.

[`legibilityWeight`](/documentation/SwiftUI/EnvironmentValues/legibilityWeight)

The font weight to apply to text.

### Actions

[`dismiss`](/documentation/SwiftUI/EnvironmentValues/dismiss)

An action that dismisses the current presentation.

[`dismissSearch`](/documentation/SwiftUI/EnvironmentValues/dismissSearch)

An action that ends the current search interaction.

[`dismissWindow`](/documentation/SwiftUI/EnvironmentValues/dismissWindow)

A window dismissal action stored in a view’s environment.

[`openImmersiveSpace`](/documentation/SwiftUI/EnvironmentValues/openImmersiveSpace)

An action that presents an immersive space.

[`dismissImmersiveSpace`](/documentation/SwiftUI/EnvironmentValues/dismissImmersiveSpace)

An immersive space dismissal action stored in a view’s environment.

[`newDocument`](/documentation/SwiftUI/EnvironmentValues/newDocument)

An action in the environment that presents a new document.

[`openDocument`](/documentation/SwiftUI/EnvironmentValues/openDocument)

An action in the environment that presents an existing document.

[`openURL`](/documentation/SwiftUI/EnvironmentValues/openURL)

An action that opens a URL.

[`openWindow`](/documentation/SwiftUI/EnvironmentValues/openWindow)

A window presentation action stored in a view’s environment.

[`pushWindow`](/documentation/SwiftUI/EnvironmentValues/pushWindow)

A window presentation action stored in a view’s environment.

[`purchase`](/documentation/SwiftUI/EnvironmentValues/purchase)

An action that starts an in-app purchase.

[`refresh`](/documentation/SwiftUI/EnvironmentValues/refresh)

A refresh action stored in a view’s environment.

[`rename`](/documentation/SwiftUI/EnvironmentValues/rename)

An action that activates the standard rename interaction.

[`resetFocus`](/documentation/SwiftUI/EnvironmentValues/resetFocus)

An action that requests the focus system to reevaluate default focus.

[`openSettings`](/documentation/SwiftUI/EnvironmentValues/openSettings)

A Settings presentation action stored in a view’s environment.

### Authentication

[`authorizationController`](/documentation/SwiftUI/EnvironmentValues/authorizationController)

A value provided in the SwiftUI environment that views can use
to perform authorization requests.

[`webAuthenticationSession`](/documentation/SwiftUI/EnvironmentValues/webAuthenticationSession)

A value provided in the SwiftUI environment that views can use to
authenticate a user through a web service.

### Controls and input

[`buttonRepeatBehavior`](/documentation/SwiftUI/EnvironmentValues/buttonRepeatBehavior)

Whether buttons with this associated environment should repeatedly
trigger their actions on prolonged interactions.

[`controlSize`](/documentation/SwiftUI/EnvironmentValues/controlSize)

The size to apply to controls within a view.

[`defaultWheelPickerItemHeight`](/documentation/SwiftUI/EnvironmentValues/defaultWheelPickerItemHeight)

The default height of an item in a wheel-style picker, such as a date
picker.

[`keyboardShortcut`](/documentation/SwiftUI/EnvironmentValues/keyboardShortcut)

The keyboard shortcut that buttons in this environment will be triggered
with.

[`menuIndicatorVisibility`](/documentation/SwiftUI/EnvironmentValues/menuIndicatorVisibility)

The menu indicator visibility to apply to controls within a view.

[`menuOrder`](/documentation/SwiftUI/EnvironmentValues/menuOrder)

The preferred order of items for menus presented from this view.

[`searchSuggestionsPlacement`](/documentation/SwiftUI/EnvironmentValues/searchSuggestionsPlacement)

The current placement of search suggestions.

[`preferredPencilDoubleTapAction`](/documentation/SwiftUI/EnvironmentValues/preferredPencilDoubleTapAction)

The action that the user prefers to perform after double-tapping their
Apple Pencil, as selected in the Settings app.

[`preferredPencilSqueezeAction`](/documentation/SwiftUI/EnvironmentValues/preferredPencilSqueezeAction)

The action that the user prefers to perform when squeezing their Apple
Pencil, as selected in the Settings app.

### Display characteristics

[`appearsActive`](/documentation/SwiftUI/EnvironmentValues/appearsActive)

Whether views and styles in this environment should prefer an active
appearance over an inactive appearance.

[`colorScheme`](/documentation/SwiftUI/EnvironmentValues/colorScheme)

The color scheme of this environment.

[`colorSchemeContrast`](/documentation/SwiftUI/EnvironmentValues/colorSchemeContrast)

The contrast associated with the color scheme of this environment.

[`displayScale`](/documentation/SwiftUI/EnvironmentValues/displayScale)

The display scale of this environment.

[`horizontalSizeClass`](/documentation/SwiftUI/EnvironmentValues/horizontalSizeClass)

The horizontal size class of this environment.

[`imageScale`](/documentation/SwiftUI/EnvironmentValues/imageScale)

The image scale for this environment.

[`pixelLength`](/documentation/SwiftUI/EnvironmentValues/pixelLength)

The size of a pixel on the screen.

[`sidebarRowSize`](/documentation/SwiftUI/EnvironmentValues/sidebarRowSize)

The current size of sidebar rows.

[`verticalSizeClass`](/documentation/SwiftUI/EnvironmentValues/verticalSizeClass)

The vertical size class of this environment.

[`immersiveSpaceDisplacement`](/documentation/SwiftUI/EnvironmentValues/immersiveSpaceDisplacement)

The displacement that the system applies to the immersive space when
moving the space away from its default position, in meters.

[`labelsVisibility`](/documentation/SwiftUI/EnvironmentValues/labelsVisibility)

The labels visibility set by [`labelsVisibility(_:)`](/documentation/SwiftUI/View/labelsVisibility(_:)).

[`materialActiveAppearance`](/documentation/SwiftUI/EnvironmentValues/materialActiveAppearance)

The behavior materials should use for their active state, defaulting to
`automatic`.

[`TabBarPlacement`](/documentation/SwiftUI/TabBarPlacement)

A placement for tabs in a tab view.

[`toolbarLabelStyle`](/documentation/SwiftUI/EnvironmentValues/toolbarLabelStyle)

The label style to apply to controls within a toolbar.

### Global objects

[`calendar`](/documentation/SwiftUI/EnvironmentValues/calendar)

The current calendar that views should use when handling dates.

[`documentConfiguration`](/documentation/SwiftUI/EnvironmentValues/documentConfiguration)

The configuration of a document in a [`DocumentGroup`](/documentation/SwiftUI/DocumentGroup).

[`locale`](/documentation/SwiftUI/EnvironmentValues/locale)

The current locale that views should use.

[`managedObjectContext`](/documentation/SwiftUI/EnvironmentValues/managedObjectContext)

[`modelContext`](/documentation/SwiftUI/EnvironmentValues/modelContext)

The SwiftData model context that will be used for queries and other
model operations within this environment.

[`timeZone`](/documentation/SwiftUI/EnvironmentValues/timeZone)

The current time zone that views should use when handling dates.

[`undoManager`](/documentation/SwiftUI/EnvironmentValues/undoManager)

The undo manager used to register a view’s undo operations.

### Scrolling

[`isScrollEnabled`](/documentation/SwiftUI/EnvironmentValues/isScrollEnabled)

A Boolean value that indicates whether any scroll views associated
with this environment allow scrolling to occur.

[`horizontalScrollIndicatorVisibility`](/documentation/SwiftUI/EnvironmentValues/horizontalScrollIndicatorVisibility)

The visibility to apply to scroll indicators of any
horizontally scrollable content.

[`verticalScrollIndicatorVisibility`](/documentation/SwiftUI/EnvironmentValues/verticalScrollIndicatorVisibility)

The visiblity to apply to scroll indicators of any
vertically scrollable content.

[`scrollDismissesKeyboardMode`](/documentation/SwiftUI/EnvironmentValues/scrollDismissesKeyboardMode)

The way that scrollable content interacts with the software keyboard.

[`horizontalScrollBounceBehavior`](/documentation/SwiftUI/EnvironmentValues/horizontalScrollBounceBehavior)

The scroll bounce mode for the horizontal axis of scrollable views.

[`verticalScrollBounceBehavior`](/documentation/SwiftUI/EnvironmentValues/verticalScrollBounceBehavior)

The scroll bounce mode for the vertical axis of scrollable views.

### State

[`editMode`](/documentation/SwiftUI/EnvironmentValues/editMode)

An indication of whether the user can edit the contents of a view
associated with this environment.

[`isActivityFullscreen`](/documentation/SwiftUI/EnvironmentValues/isActivityFullscreen)

A Boolean value that indicates whether the Live Activity appears in a
full-screen presentation.

[`isEnabled`](/documentation/SwiftUI/EnvironmentValues/isEnabled)

A Boolean value that indicates whether the view associated with this
environment allows user interaction.

[`isFocused`](/documentation/SwiftUI/EnvironmentValues/isFocused)

Returns whether the nearest focusable ancestor has focus.

[`isFocusEffectEnabled`](/documentation/SwiftUI/EnvironmentValues/isFocusEffectEnabled)

A Boolean value that indicates whether the view associated with this
environment allows focus effects to be displayed.

[`isHoverEffectEnabled`](/documentation/SwiftUI/EnvironmentValues/isHoverEffectEnabled)

A Boolean value that indicates whether the view associated with this
environment allows hover effects to be displayed.

[`isLuminanceReduced`](/documentation/SwiftUI/EnvironmentValues/isLuminanceReduced)

A Boolean value that indicates whether the display or environment currently requires
reduced luminance.

[`isPresented`](/documentation/SwiftUI/EnvironmentValues/isPresented)

A Boolean value that indicates whether the view associated with this
environment is currently presented.

[`isSceneCaptured`](/documentation/SwiftUI/EnvironmentValues/isSceneCaptured)

The current capture state.

[`isSearching`](/documentation/SwiftUI/EnvironmentValues/isSearching)

A Boolean value that indicates when the user is searching.

[`isTabBarShowingSections`](/documentation/SwiftUI/EnvironmentValues/isTabBarShowingSections)

A Boolean value that determines whether a tab view shows the
expanded contents of a tab section.

[`scenePhase`](/documentation/SwiftUI/EnvironmentValues/scenePhase)

The current phase of the scene.

[`supportsMultipleWindows`](/documentation/SwiftUI/EnvironmentValues/supportsMultipleWindows)

A Boolean value that indicates whether the current platform supports
opening multiple windows.

### StoreKit configuration

[`displayStoreKitMessage`](/documentation/SwiftUI/EnvironmentValues/displayStoreKitMessage)

[`requestReview`](/documentation/SwiftUI/EnvironmentValues/requestReview)

### Text styles

[`allowsTightening`](/documentation/SwiftUI/EnvironmentValues/allowsTightening)

A Boolean value that indicates whether inter-character spacing should
tighten to fit the text into the available space.

[`autocorrectionDisabled`](/documentation/SwiftUI/EnvironmentValues/autocorrectionDisabled)

A Boolean value that determines whether the view hierarchy has
auto-correction enabled.

[`dynamicTypeSize`](/documentation/SwiftUI/EnvironmentValues/dynamicTypeSize)

The current Dynamic Type size.

[`font`](/documentation/SwiftUI/EnvironmentValues/font)

The default font of this environment.

[`layoutDirection`](/documentation/SwiftUI/EnvironmentValues/layoutDirection)

The layout direction associated with the current environment.

[`lineLimit`](/documentation/SwiftUI/EnvironmentValues/lineLimit)

The maximum number of lines that text can occupy in a view.

[`lineSpacing`](/documentation/SwiftUI/EnvironmentValues/lineSpacing)

The distance in points between the bottom of one line fragment and the
top of the next.

[`minimumScaleFactor`](/documentation/SwiftUI/EnvironmentValues/minimumScaleFactor)

The minimum permissible proportion to shrink the font size to fit
the text into the available space.

[`multilineTextAlignment`](/documentation/SwiftUI/EnvironmentValues/multilineTextAlignment)

An environment value that indicates how a text view aligns its lines
when the content wraps or contains newlines.

[`textCase`](/documentation/SwiftUI/EnvironmentValues/textCase)

A stylistic override to transform the case of `Text` when displayed,
using the environment’s locale.

[`textSelectionAffinity`](/documentation/SwiftUI/EnvironmentValues/textSelectionAffinity)

A representation of the direction or association of a selection or cursor
relative to a text character. This concept becomes much more prominent
when dealing with bidirectional text (text that contains both LTR and RTL
scripts, like English and Arabic combined).

[`truncationMode`](/documentation/SwiftUI/EnvironmentValues/truncationMode)

A value that indicates how the layout truncates the last line of text to
fit into the available space.

### View attributes

[`allowedDynamicRange`](/documentation/SwiftUI/EnvironmentValues/allowedDynamicRange)

The allowed dynamic range for the view, or nil.

[`backgroundMaterial`](/documentation/SwiftUI/EnvironmentValues/backgroundMaterial)

The material underneath the current view.

[`backgroundProminence`](/documentation/SwiftUI/EnvironmentValues/backgroundProminence)

The prominence of the background underneath views associated with this
environment.

[`backgroundStyle`](/documentation/SwiftUI/EnvironmentValues/backgroundStyle)

An optional style that overrides the default system background
style when set.

[`badgeProminence`](/documentation/SwiftUI/EnvironmentValues/badgeProminence)

The prominence to apply to badges associated with this environment.

[`contentTransition`](/documentation/SwiftUI/EnvironmentValues/contentTransition)

The current method of animating the contents of views.

[`contentTransitionAddsDrawingGroup`](/documentation/SwiftUI/EnvironmentValues/contentTransitionAddsDrawingGroup)

A Boolean value that controls whether views that render content
transitions use GPU-accelerated rendering.

[`defaultMinListHeaderHeight`](/documentation/SwiftUI/EnvironmentValues/defaultMinListHeaderHeight)

The default minimum height of a header in a list.

[`defaultMinListRowHeight`](/documentation/SwiftUI/EnvironmentValues/defaultMinListRowHeight)

The default minimum height of rows in a list.

[`headerProminence`](/documentation/SwiftUI/EnvironmentValues/headerProminence)

The prominence to apply to section headers within a view.

[`physicalMetrics`](/documentation/SwiftUI/EnvironmentValues/physicalMetrics)

The physical metrics associated with a scene.

[`realityKitScene`](/documentation/SwiftUI/EnvironmentValues/realityKitScene)

[`realityViewCameraControls`](/documentation/SwiftUI/EnvironmentValues/realityViewCameraControls)

The camera controls for the reality view.

[`redactionReasons`](/documentation/SwiftUI/EnvironmentValues/redactionReasons)

The current redaction reasons applied to the view hierarchy.

[`springLoadingBehavior`](/documentation/SwiftUI/EnvironmentValues/springLoadingBehavior)

The behavior of spring loaded interactions for the views associated
with this environment.

[`symbolRenderingMode`](/documentation/SwiftUI/EnvironmentValues/symbolRenderingMode)

The current symbol rendering mode, or `nil` denoting that the
mode is picked automatically using the current image and
foreground style as parameters.

[`symbolVariants`](/documentation/SwiftUI/EnvironmentValues/symbolVariants)

The symbol variant to use in this environment.

[`worldTrackingLimitations`](/documentation/SwiftUI/EnvironmentValues/worldTrackingLimitations)

The current limitations of the device tracking the user’s surroundings.

### Widgets

[`showsWidgetContainerBackground`](/documentation/SwiftUI/EnvironmentValues/showsWidgetContainerBackground)

An environment variable that indicates whether the background of a widget appears.

[`showsWidgetLabel`](/documentation/SwiftUI/EnvironmentValues/showsWidgetLabel)

A Boolean value that indicates whether an accessory family widget can
display an accessory label.

[`widgetFamily`](/documentation/SwiftUI/EnvironmentValues/widgetFamily)

The template of the widget — small, medium, or large.

[`widgetRenderingMode`](/documentation/SwiftUI/EnvironmentValues/widgetRenderingMode)

The widget’s rendering mode, based on where the system is displaying it.

[`widgetContentMargins`](/documentation/SwiftUI/EnvironmentValues/widgetContentMargins)

A property that identifies the content margins of a widget.

### Deprecated environment values

[`disableAutocorrection`](/documentation/SwiftUI/EnvironmentValues/disableAutocorrection)

A Boolean value that determines whether the view hierarchy has
auto-correction enabled.

[`sizeCategory`](/documentation/SwiftUI/EnvironmentValues/sizeCategory)

The size of content.

[`presentationMode`](/documentation/SwiftUI/EnvironmentValues/presentationMode)

A binding to the current presentation mode of the view associated with this
environment.

[`PresentationMode`](/documentation/SwiftUI/PresentationMode)

An indication whether a view is currently presented by another view.

[`complicationRenderingMode`](/documentation/SwiftUI/EnvironmentValues/complicationRenderingMode)

The complication rendering mode for the current environment.

[`controlActiveState`](/documentation/SwiftUI/EnvironmentValues/controlActiveState)

The active appearance expected of controls in a window.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)