SettingsKit 3.0.0 — Composable presentations and live settings search

SettingsKit 3.0.0 — Composable presentations and live settings search

SettingsKit 3 is a major update to how settings are composed, presented, and searched. Keep the built-in sidebar or single-column interface, or put the same settings runtime inside your own navigation, tabs, cards, and toolbars. Search results retain live controls, and indexing is scoped to each settings host.

This release contains breaking public API changes. Read the migration guide before upgrading from 2.x. The major version reflects those compatibility changes, as well as the expanded presentation API.

Added

• App-owned presentations. SettingsHost and SettingsPresentationContext expose root content, search content, metadata, search results, navigation paths, and split-view selection. Custom layouts can resolve live destinations and indexed controls through the host's context.
• Independent group styling. SettingsGroupStyle, AnySettingsGroupStyle, and .settingsGroupStyle(...) customize groups without taking ownership of the surrounding navigation and layout.
• Explicit search placement. Built-in styles accept .root, .destinations, .all, or .none. iOS destination pages search their own hierarchy; iOS 26 requests a compact native toolbar search control.
• Search exclusion. .unindexed() excludes a group or indexed control and its descendants while retaining navigation, identity, bindings, and styling. Custom search engines can inspect isIncludedInSearch.
• Explicit identities. .settingsID(...) distinguishes same-named sibling groups; .indexed(_:tags:id:) distinguishes repeated controls. Descendant metadata is scoped to its ancestor path.
• Programmatic destination requests. SettingsNavigationRequest opens uniquely named routes, including pages inside inline sections and nested destinations, with an optional success callback.
• Introductory rows. .settingsIntroduction() coordinates built-in iOS destination titles with introductory-row visibility on iOS 18 and later, including Reduce Motion handling.
• Structural index revisions. settingsIndexRevision lets containers rebuild metadata when hierarchy, titles, tags, or exclusions change without indexing on every live-value update.

Fixed

• Search includes direct indexed controls in sections that also contain navigation groups, and resolves deeper matches to their containing navigation page.
• Navigation search results retain matching live controls alongside the destination link. Search-result identity follows the group identity.
• Same-titled sections and controls in different ancestor paths no longer share registry entries. Separate settings hosts keep their live-view registries isolated.
• macOS sidebar and search destinations resolve live registered content after presentation. Central value-based navigation and detail remounting address controls displaying stale values when revisiting a page.
• Settings content is mounted as a SwiftUI value rather than eagerly evaluating its body for destination registration. Host body evaluation no longer constructs the metadata index.
• The demo's macOS 27 tab picker is guarded for the matching compiler, preserving its segmented fallback when building with Xcode 26.

Changed

• Groups carry semantic hierarchy and optional SF Symbol metadata; presentation styles own row decoration.
• The single-column style uses Form. The macOS sidebar detail surface uses cards, inline sections, and nested navigation rows.
• The demo expands into built-in examples, custom destinations, a complete custom presentation, a tabbed cards example, shared state, and diagnostics. Shared Xcode schemes are included, and the demo enables Mac Catalyst compatibility.
• DocC guides now cover composition, indexing, search, custom presentation, styling, and macOS navigation state. The README reflects the version 3 API.
• Repository contribution, review, and release workflow documentation and templates are included.

Breaking changes and migration

• SettingsGroup<Content, Icon> becomes SettingsGroup<Content>. Remove the icon: builder; use systemImage: for an SF Symbol and a custom style for decoration. SettingsIcon is removed.
• CustomSettingsGroup removes systemImage:. Its destination remains arbitrary SwiftUI content; move row decoration into a style.
• SettingsStyle removes item styling requirements and SettingsItemConfiguration. Style individual controls using SwiftUI modifiers and control styles.
• SettingsGroupConfiguration exposes id and systemImage in place of iconName and iconView. Container configuration adds selectedGroup.
• SettingsNode.group replaces icon with systemImage and adds a trailing searchable value. SettingsNode.item removes icon. Update construction, property access, and enum pattern matches.
• Custom SettingsContent implementations that manually build nodes must support makeNodes(in:) and forward the supplied scope. Custom search engines must respect excluded subtrees. Containers with changing search structure must update settingsIndexRevision.

The migration guide includes examples and presentation differences.

Requirements and installation

Swift tools 6.2. Minimum package targets remain iOS 17, macOS 14, tvOS 17, watchOS 10, and visionOS 1. Newer search and introduction behaviors use platform availability checks. Demo deployment targets are separate from the library's minimums.

.package(url: "https://github.com/aeastr/SettingsKit.git", from: "3.0.0")

Validation

• macOS package build and all 26 XCTest cases passed using Xcode 26.6.
• macOS and iOS demo builds passed using Xcode 26.6 with code signing disabled. The macOS build includes arm64 and x86_64; iOS targets arm64.
• Automated coverage includes search identity and ownership, navigation request resolution, host isolation, introduction metadata, search exclusion, and deferred destination lookup.
• Device UI behavior, scroll animation, accessibility interaction, Mac Catalyst, tvOS, watchOS, and visionOS builds were not validated for this release. Package tests establish metadata behavior, not those platform interactions.

Full changes: 2.0.1…3.0.0.