Declaration
compose().preferredColorScheme(
colorScheme: SwiftUI.ColorScheme | null
)nonisolated func preferredColorScheme(
_ colorScheme: ColorScheme?
) -> some ViewParameters
colorScheme*SwiftUI.ColorScheme | nullThe preferred color scheme for this view, or
nilto indicate no preference.
Return value
A view that sets the color scheme.
Discussion
Use one of the values in ColorScheme with this modifier to set a
preferred color scheme for the nearest enclosing presentation, like a
popover, a sheet, or a window. The value that you set overrides the
user's Dark Mode selection for that presentation. In the example below,
the Toggle controls an isDarkMode state variable, which in turn
controls the color scheme of the sheet that contains the toggle:
@State private var isPresented = false
@State private var isDarkMode = true
var body: some View {
Button("Show Sheet") {
isPresented = true
}
.sheet(isPresented: $isPresented) {
List {
Toggle("Dark Mode", isOn: $isDarkMode)
}
.preferredColorScheme(isDarkMode ? .dark : nil)
}
}If you apply the modifier to any of the views in the sheet --- which in
this case are a List and a Toggle --- the value that you set
propagates up through the view hierarchy to the enclosing
presentation, or until another color scheme modifier higher in the
hierarchy overrides it. The value you set also flows down to all child
views of the enclosing presentation.
Pass nil to indicate that there is no preferred color scheme for this
view. This is useful in cases where a preferred color scheme should only
be applied conditionally. In the previous example, the sheet will prefer
dark mode when isDarkMode is set to true, but otherwise defer to the
color scheme as determined by the system.
Multiple views in the same view hierarchy can set a preferred color
scheme. Applying this modifier overrides any existing preferred color
scheme set for the view, such as by one of its subviews. If there are
conflicting, non-nil color scheme preferences set by parallel branches
of the view hierarchy, the system will prioritize the first non-nil
preference based on the order of the views. In the example below, the
preferred color scheme for the entire view will resolve to .dark, from
the second view:
VStack {
Text("First")
.preferredColorScheme(.light)
.preferredColorScheme(nil) // overrides `.light`
Text("Second")
.preferredColorScheme(.dark)
Text("Third")
.preferredColorScheme(.light)
}A common use for this modifier is to create side-by-side previews of the same view with light and dark appearances:
struct MyView_Previews: PreviewProvider {
static var previews: some View {
MyView().preferredColorScheme(.light)
MyView().preferredColorScheme(.dark)
}
}If you need to detect the color scheme that currently applies to a view,
read the EnvironmentValues.colorScheme environment value:
@Environment(\.colorScheme) private var colorScheme
var body: some View {
Text(colorScheme == .dark ? "Dark" : "Light")
}See also
More in Appearance.
- backgroundSets the view's background to a style.
- badgeGenerates a badge for the view from a localized string resource.
- badgeProminenceSpecifies the prominence of badges created by this view.
- borderAdds a border to this view with the specified style and width.
- buttonSizingThe preferred sizing behavior of buttons in the view hierarchy.
- containerBackgroundSets the container background of the enclosing container using a view.
- headerProminenceSets the header prominence for this view.
- hiddenHides this view unconditionally.
- imageScaleScales images within the view according to one of the relative sizes available including small, medium, and large images sizes.
- labelIconToTitleSpacingSet the spacing between the icon and title in labels.
- labelReservedIconWidthSet the width reserved for icons in labels.
- labelsHiddenHides the labels of any controls contained within this view.