# Settings chrome

> Configure the top bar, the gear, and what the chrome shows.

The chrome (top bar, lock for keep-open, and Settings gear) is driven by
flags on `NookConfiguration.topBar`. You can replace the leading identity
(label and icon), strip the top bar entirely, or keep the bar while dropping
the gear.

```swift
var configuration = NookConfiguration()

// Replace the leading identity. Defaults: title "Home", OpenNook brand mark.
configuration.topBar.leadingTitle = { _ in "Today" }
configuration.topBar.leadingIcon = "house"  // SF Symbol override; nil keeps the brand mark

// Chrome flags.
configuration.topBar.showsTopBar = true   // false strips top bar + gear + lock
configuration.topBar.showsSettings = true // false drops the gear (top bar stays)
configuration.topBar.notchClearance = .automatic  // .manual lets content run up beside the notch

// Move the lock or the gear somewhere else, keeping the feature.
configuration.topBar.showsKeepOpenButton = true  // false takes the lock out of the bar
configuration.topBar.showsSettingsButton = true  // false takes the gear out of the bar
```

## `showsTopBar`

When `false`, the chrome shell renders only your home view inside the
expanded surface. No top bar, no gear, no lock. Use this when your view
owns the entire surface.

The content still starts below the notch, where the bar would have ended. To put icons
beside the notch, or to let the content run up to the top, see
[Clearing the notch](/guides/layout-and-insets/#clearing-the-notch).

## `showsSettings`

When `false`, the top bar remains (so the lock and any leading identity are
still visible) but the gear is removed. Use this when you ship without
exposing the framework's Settings panels.

## `showsKeepOpenButton` / `showsSettingsButton`

Each removes one glyph from the top bar *without* removing its feature. Keep-open
stays in Settings and the menu bar, and Settings stays reachable from the menu bar
and `AppCoordinator.showSettings()`. Use them to show the controls somewhere else -
typically in a [companion surface](/guides/companion-surfaces/#moving-the-lock-and-gear)
with the framework's `NookKeepOpenButton` and `NookSettingsButton`, or in your own
controls through the `\.nookChromeActions` environment value:

```swift
configuration.topBar.showsKeepOpenButton = false
configuration.topBar.showsSettingsButton = false
configuration.addCompanion(id: "chrome-controls", anchor: .trailing, hidesInSettings: false) {
    ChromeControls()  // a VStack of NookKeepOpenButton() and NookSettingsButton()
}
```

## `topBar.leadingTitle` / `topBar.leadingIcon`

The leading cluster is the home glyph plus a label on the home surface. Both
are functions of `AppState`, so they can follow your product state.

Defaults are `"Home"` for the title and the OpenNook brand mark for the icon
(`leadingIcon` is `nil`). Set `leadingIcon` to an SF Symbol name, such as
`"house"`, to use your own glyph. Set `leadingTitle` to return an empty string
if you want a title-only cluster with no icon override.

## See also

- [Companion surfaces](/guides/companion-surfaces/) - floating the lock and gear, or
  any host control, beside the nook.
- [Theming](/guides/theming/#custom-settings-surface) - replace the built-in
  Settings screen with `setSettings(_:)`, the companion to `showsSettings`.
- [Your first nook](/start/first-nook/#2-customize-via-nookconfiguration) - where
  the `topBar` flags first appear, alongside the other `NookConfiguration` knobs.