rshankras/visionos-widgets

visionOS Widgets

Patterns for building widgets that live in physical space on visionOS. Covers mounting styles, textures, proximity-aware detail levels, spatial widget families, and rendering modes.

When This Skill Activates

Use this skill when the user:

• Asks to create or adapt a widget for visionOS
• Mentions mounting styles (elevated, recessed)
• Wants glass or paper texture on a widget
• Asks about proximity awareness or level of detail in widgets
• Mentions spatial widget families or .systemExtraLargePortrait
• Wants to control container backgrounds or rendering modes (full color vs accented)
• Is porting an existing iOS/iPadOS widget to visionOS

Decision Tree

What do you need for your visionOS widget?
|
+- Where should the widget appear?
|  +- On a surface (table, shelf) -> .elevated (default)
|  +- Embedded in a wall -> .recessed
|  +- Both -> .supportedMountingStyles([.elevated, .recessed])
|
+- What visual treatment?
|  +- Transparent, blends with environment -> .glass (default)
|  +- Opaque, poster-like appearance -> .paper
|
+- How should it respond to user distance?
|  +- Full detail when close -> @Environment(\.levelOfDetail) == .default
|  +- Simplified when far -> @Environment(\.levelOfDetail) == .simplified
|
+- What size families?
|  +- Standard -> .systemSmall, .systemMedium, .systemLarge, .systemExtraLarge
|  +- Tall portrait -> .systemExtraLargePortrait (visionOS only)
|
+- How should colors render?
|  +- Full color (default) -> No extra work
|  +- System-tinted monochrome -> Mark backgrounds with .containerBackground(for:)

API Availability

| API | Minimum Version | Notes | |-----|----------------|-------| | WidgetKit on visionOS | visionOS 1.0 | Basic widget support | | .containerBackground(for: .widget) | visionOS 1.0 | Removable background marking | | @Environment(\.showsWidgetContainerBackground) | visionOS 1.0 | Background visibility check | | .supportedMountingStyles() | visionOS 2.0 | Elevated and recessed placement | | .widgetTexture(.glass / .paper) | visionOS 2.0 | Widget surface material | | @Environment(\.levelOfDetail) | visionOS 2.0 | Proximity-aware layouts | | .systemExtraLargePortrait | visionOS 2.0 | Tall portrait widget family |

Complete Widget Example

This example demonstrates mounting styles, textures, families, and proximity awareness together:

struct MyWidget: Widget {
    var body: some WidgetConfiguration {
        StaticConfiguration(
            kind: "com.example.mywidget",
            provider: Provider()
        ) { entry in
            MyWidgetView(entry: entry)
        }
        .supportedFamilies([
            .systemSmall, .systemMedium, .systemLarge,
            .systemExtraLarge, .systemExtraLargePortrait
        ])
        .supportedMountingStyles([.elevated, .recessed])
        .widgetTexture(.glass)        // .glass is default, .paper for opaque
    }
}

Mounting styles: .elevated (default) sits on surfaces like tables. .recessed embeds into walls like a framed picture. Omit .supportedMountingStyles() to use elevated only. Recessed works only on vertical surfaces — placements on horizontal surfaces are always elevated. On horizontal surfaces the system also applies a gentle tilt toward the user; design for that angle rather than fighting it.

Textures: .glass (default) is transparent and blends with the environment. .paper is opaque and poster-like, best for rich imagery.

Spatial Behavior (WWDC25)

Widgets are permanent room fixtures: they persist across sessions, room changes, and device power cycles, and they snap only to physical surfaces — never to virtual environments. Multiple instances of the same widget can coexist in a room.

• User resizing: a corner affordance lets users scale a widget from 75% to 125% of its template size — layouts must survive the entire range.
• Frames: users pick from five frame widths (thin to thick), independent of template size. The recessed style fixes the frame width.
• Frame tinting: the widget frame always receives the user's color tint and cannot opt out. Even when the background opts out of tinting, foregrounds must hold up under all 7 light and 7 dark system palettes.
• Assets: widgets render at real-world scale — ship high-resolution assets so imagery stays sharp at close range.

Proximity Awareness (Level of Detail)

The system tracks user distance and transitions automatically, with animation, between exactly two detail levels: .default when the user is close and .simplified at a distance. In the simplified state, cut information density and enlarge the key info.

struct MyWidgetView: View {
    let entry: Provider.Entry
    @Environment(\.levelOfDetail) private var levelOfDetail

    var body: some View {
        switch levelOfDetail {
        case .default:
            VStack(alignment: .leading, spacing: 8) {
                Text(entry.title).font(.headline)
                Text(entry.subtitle).font(.subheadline).foregroundStyle(.secondary)
                DetailChart(data: entry.chartData)
            }
            .padding()
        case .simplified:
            VStack(spacing: 4) {
                Image(systemName: entry.iconName).font(.largeTitle)
                Text(entry.title).font(.headline)
            }
            .padding()
        @unknown default:
            Text(entry.title).padding()
        }
    }
}

Always handle @unknown default for forward compatibility.

Widget Families

| Family | Description | |--------|-------------| | .systemSmall | Compact square -- glanceable info | | .systemMedium | Wide rectangle -- two-column or list preview | | .systemLarge | Large square -- charts, detailed content | | .systemExtraLarge | Extra-large landscape -- dashboards | | .systemExtraLargePortrait | Extra-large portrait -- visionOS only; wall-art "statement" widgets |

Guard the visionOS-only family in multiplatform targets:

.supportedFamilies({
    var families: [WidgetFamily] = [.systemSmall, .systemMedium, .systemLarge]
    #if os(visionOS)
    families.append(.systemExtraLargePortrait)
    #endif
    return families
}())

Container Backgrounds and Rendering Modes

In accented rendering mode, the system removes backgrounds and applies a tint color. Mark removable backgrounds so the widget renders correctly in both modes.

struct MyWidgetView: View {
    let entry: Provider.Entry
    @Environment(\.showsWidgetContainerBackground) var showsBackground

    var body: some View {
        VStack {
            Image(systemName: "star.fill").font(.largeTitle)
            Text(entry.title)
                .font(.headline)
                .foregroundStyle(showsBackground ? .white : .primary)
        }
        .padding()
        .containerBackground(for: .widget) {
            LinearGradient(
                colors: [.blue, .purple],
                startPoint: .topLeading,
                endPoint: .bottomTrailing
            )
        }
    }
}

• Full color (default): All colors render intact.
• Accented: Container background is removed; system applies a monochrome tint.

Previewing visionOS Widgets

#Preview("Close Up", as: .systemSmall) {
    MyWidget()
} timelineProvider: {
    Provider()
}

#Preview("Extra Large Portrait", as: .systemExtraLargePortrait) {
    MyWidget()
} timelineProvider: {
    Provider()
}

Top 5 Mistakes

| # | Mistake | Fix | |---|---------|-----| | 1 | Missing .containerBackground(for: .widget) -- accented mode renders blank | Always wrap backgrounds in .containerBackground(for: .widget) { } | | 2 | Ignoring levelOfDetail -- detailed views unreadable from across the room | Provide a .simplified layout with larger text, fewer elements | | 3 | Using .systemExtraLargePortrait on iOS -- build error or runtime crash | Guard with #if os(visionOS) or visionOS-only targets | | 4 | Hardcoding colors that clash with glass texture | Use .foregroundStyle(.primary / .secondary) and system colors | | 5 | No @unknown default in levelOfDetail switch | Always include for forward compatibility |

Anti-Patterns

// ❌ No container background — accented mode shows nothing
struct BadWidgetView: View {
    var body: some View {
        ZStack {
            Color.blue  // Not marked as removable
            Text("Hello")
        }
    }
}

// ✅ Background marked as removable
struct GoodWidgetView: View {
    var body: some View {
        Text("Hello")
            .containerBackground(for: .widget) { Color.blue }
    }
}

// ❌ Same complex layout at all distances
struct BadProximityView: View {
    var body: some View {
        VStack {
            Text(entry.title).font(.caption2)  // Unreadable far away
            DetailChart(data: entry.data)
        }
    }
}

// ✅ Simplified layout when far away
struct GoodProximityView: View {
    @Environment(\.levelOfDetail) private var levelOfDetail
    var body: some View {
        switch levelOfDetail {
        case .default: DetailedLayout(entry: entry)
        case .simplified: SimplifiedLayout(entry: entry)
        @unknown default: SimplifiedLayout(entry: entry)
        }
    }
}

Review Checklist

Mounting and Texture

• [ ] Mounting style explicitly set if widget should appear recessed or support both
• [ ] Texture set to .paper for widgets with rich imagery
• [ ] Widget tested in both elevated and recessed placements (if both supported)
• [ ] Layout survives user resizing from 75% to 125% of the template size

Proximity Awareness

• [ ] @Environment(\.levelOfDetail) provides simplified layout for distant viewers
• [ ] .simplified layout uses larger text, fewer elements, high-contrast visuals
• [ ] @unknown default case present in levelOfDetail switch

Families and Layout

• [ ] .systemExtraLargePortrait guarded with #if os(visionOS) in multiplatform targets
• [ ] Widget content adapts to each supported family size
• [ ] Layout tested in all declared family sizes via Xcode previews

Backgrounds and Rendering

• [ ] .containerBackground(for: .widget) { } used to mark removable backgrounds
• [ ] Widget renders correctly in both full color and accented modes
• [ ] showsWidgetContainerBackground checked if foreground colors depend on background
• [ ] System semantic colors used for glass texture compatibility
• [ ] Foreground legible under all 7 light and 7 dark frame-tint palettes

References

• Widgets for visionOS (WWDC)
• WidgetKit
• visionOS Human Interface Guidelines - Widgets