---
title: "visionOS PDF viewer toolbar customization | Nutrient SDK"
canonical_url: "https://www.nutrient.io/guides/ios/user-interface/main-toolbar-visionos/"
md_url: "https://www.nutrient.io/guides/ios/user-interface/main-toolbar-visionos.md"
last_updated: "2026-05-25T18:42:17.783Z"
description: "Learn how to customize the toolbar in our iOS and visionOS PDF viewers with our easy-to-follow guides and enhance your user experience."
---

# Customizing the toolbar in our visionOS PDF viewer

### iOS

[iOS](https://www.nutrient.io/guides/ios/user-interface/main-toolbar.md)

### visionOS

[visionOS](https://www.nutrient.io/guides/ios/user-interface/main-toolbar-visionos.md)

On visionOS, Nutrient’s main toolbar is, by default, added as an ornament anchored to the top of the window containing [`PDFViewController`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfviewcontroller). This is in contrast to iOS and macOS, where Nutrient’s main toolbar buttons are inside the app window in a navigation bar.

## Using ornaments

The new system feature of ornaments in visionOS enables us to expand our user interface (UI) outside the scope of a window, making it easier to show auxiliary content when compared to other Apple platforms. This enables us to move the toolbar items to ornaments, compared to the traditional navigation bar. In turn, this makes the main content area, where the PDF page is displayed, free of clutter, allowing users to focus on the actual content.

With a new API designed for Swift, the toolbar is completely configurable and allows you to add custom items to it as well.

## Customizing the toolbar

The new toolbar makes use of a new [`OrnamentItem`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/ornamentitem) API that has been specifically designed for this purpose. The default ornament items provided by Nutrient can be found on [`PDFViewController`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfviewcontroller) (similar to our longstanding [bar button item API](https://www.nutrient.io/guides/ios/user-interface/main-toolbar.md) for iOS and Mac Catalyst).

```swift

let controller = PDFViewController(document:...)

// Specifying a set of ornament items for the document view mode.
controller.setMainToolbarOrnamentItems([
controller.backOrnamentItem,
controller.titleOrnamentItem,
OrnamentItem(kind:.divider),
controller.contentEditingOrnamentItem,
controller.annotationToolsOrnamentItem
], for:.document)

// Ornament items for the content editing view mode.
controller.setMainToolbarOrnamentItems([
controller.backOrnamentItem,
controller.titleOrnamentItem,
OrnamentItem(kind:.divider),
controller.contentEditingOrnamentItem,
], for:.contentEditing)

```

The order of the ornament items in the array determines the position in the toolbar. You’ll have to manually add [`backOrnamentItem`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfviewcontroller/backornamentitem) and [`titleOrnamentItem`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfviewcontroller/titleornamentitem) if you want to display the back button and the title, respectively, on your toolbar.

## Adding custom items to the toolbar

Create custom toolbar items using the [`OrnamentItem(kind:)`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/ornamentitem/init(kind:isenabled:isselected:ishighlightable:)) API. This API allows you to add three kinds of items defined with [`OrnamentItem.Kind`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/ornamentitem/kind-swift.enum):

- Button — To add a custom button, use [`OrnamentItem.Kind.button`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/ornamentitem/kind-swift.enum/button(configuration:)). This enum case has an associated value of type [`ButtonConfiguration`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/ornamentitem/buttonconfiguration), which you should use to specify the button title, image, and action.

```swift

let customItem = OrnamentItem(kind:.button(configuration:.init(title: "Custom Item Title", image: UIImage(named: "customImage"),
     action: { sender in
     // Perform custom action here on ornament item tap.
}, showTitle: true, isHighlightable: true)))

```

- Title — Use [`OrnamentItem.Kind.title`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/ornamentitem/kind-swift.enum/title(provider:)) to add title text to the toolbar.

```swift

let customTitleItem = OrnamentItem(kind:.title(provider: { getMyCustomTitle() }))

```

- Divider — This item can be created using [`OrnamentItem.Kind.divider`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/ornamentitem/kind-swift.enum/divider), which adds a horizontal divider between two items. This is useful for creating a visible segregation between different kinds of items.

All the above custom items can be added to the toolbar using the [`PDFViewController.setMainToolbarOrnamentItems(_ items: [OrnamentItem], for viewMode: ViewMode)`][set-maintoolbar-ornaments-API] API.

## Showing an ornament when PDFViewController is a child view controller

[`PDFViewController`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfviewcontroller) displays the main toolbar, annotation toolbar, and scrubber bar as ornaments. Ornaments have to be added to the [`ornaments`](https://developer.apple.com/documentation/uikit/uiviewcontroller/4246725-ornaments) property on the `UIViewController` when using UIKit.

[`PDFViewController`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfviewcontroller) ornaments, if specified, will automatically be displayed along with the ornaments of their parent view controller, as this is the default system behavior.

If you’re displaying `PDFViewController` deeper in the hierarchy — i.e. not as the root controller of a window or the child controller of the root — you’ll have to manually assign `PDFViewController.ornaments` to the `ornaments` property of the `UIViewController` being displayed at the the root level.

## Displaying main toolbar buttons in the navigation bar

Use [`PDFConfiguration.mainToolbarMode`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfconfiguration/maintoolbarmode-swift.property) to set the kind of the main toolbar on visionOS. Nutrient defaults to [`PDFConfiguration.MainToolbarMode.ornament`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfconfiguration/maintoolbarmode-swift.enum), where the toolbar is added as an ornament. To show the main toolbar buttons in a navigation bar, set the [`mainToolbarMode`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfconfiguration/maintoolbarmode-swift.property) property to [`.navigationBar`](https://www.nutrient.io/api/ios/documentation/pspdfkitui/pdfconfiguration/maintoolbarmode-swift.enum/navigationbar).

```swift

let pdfController = PDFViewController(document:...) {
    // Displays the main toolbar as a navigation bar.
    $0.mainToolbarMode =.navigationBar
}

```
---

## Related pages

- [Customizing PDF viewer styling on iOS](/guides/ios/customizing-the-interface/appearance-styling.md)
- [Editing PDFs in our iOS viewer](/guides/ios/features/document-editor-ui.md)
- [Customizing our iOS PDF viewer](/guides/ios/user-interface.md)
- [Localization: Change languages in our iOS PDF viewer](/guides/ios/features/localization.md)
- [Customizing the toolbar in our iOS PDF viewer](/guides/ios/user-interface/main-toolbar.md)
- [Overriding classes in our iOS viewer](/guides/ios/getting-started/overriding-classes.md)
- [Customize electronic signatures UI on iOS](/guides/ios/signatures/customizing-the-signature-user-interface.md)
- [Customizing menus on iOS](/guides/ios/customizing-the-interface/customizing-menus.md)