NavigationBar

NavigationBar is a component that displays a title, optional back button, and toolbar items. It's automatically used by StandardPage when a `navigationTitle` is provided, following iOS Human Interface Guidelines and SwiftUI's navigation bar design patterns.

Prop	Type	Required	Description
`title`	`string`	No	Navigation bar title
`showBackButton`	`boolean`	No	Whether to show back button Default: `false`
`onBack`	`() => void`	No	Callback when back button is clicked
`toolbarItems`	`ReactNode`	No	Toolbar items to display on the right side

Overview

NavigationBar is a component that displays a title, optional back button, and toolbar items. It's automatically used by StandardPage when a navigationTitle is provided, following iOS Human Interface Guidelines and SwiftUI's navigation bar design patterns.

SwiftUI Correspondence: Similar to SwiftUI's .navigationTitle() and .toolbar() modifiers.

Basic Usage

NavigationBar is typically used automatically through StandardPage's navigationTitle prop:

NavigationBar can also be used directly:

Automatic Back Button

The back button automatically appears when the page is not the root page:

Add toolbar items on the right side of the navigation bar:

<StandardPage
  id="edit"
  navigationTitle="Edit Profile"
  toolbarItems={<Button onClick={handleSave}>Save</Button>}
>
  <Form>...</Form>
</StandardPage>

Custom Back Button Behavior

The back button automatically calls dismiss() from the navigation context. If you need custom behavior, you can access the navigation context:

import { useNaviContext } from '@swiftuijs/ui'

function CustomPage() {
  const navi = useNaviContext()

  const handleCustomBack = () => {
    // Custom logic before going back
    if (hasUnsavedChanges) {
      showConfirmDialog(() => navi.dismiss())
    } else {
      navi.dismiss()
    }
  }

  return (
    <StandardPage
      id="custom"
      navigationTitle="Custom Page"
      // Note: Back button behavior is handled automatically
      // For custom behavior, you might need to hide the default
      // and add a custom button in toolbarItems
    >
      ...
    </StandardPage>
  )
}

Prop	Type	Default	Description
`navigationTitle`	`string`	-	Title to display in navigation bar. When provided, navigation bar is shown.
`toolbarItems`	`ReactNode`	-	Items to display on the right side of navigation bar.

NavigationBar Props (Internal)

NavigationBar is used internally, but you can access it directly if needed:

Prop	Type	Default	Description
`title`	`string`	-	Navigation bar title
`showBackButton`	`boolean`	`false`	Whether to show back button
`onBack`	`() => void`	-	Callback when back button is clicked
`toolbarItems`	`ReactNode`	-	Toolbar items to display

Common Patterns

Master-Detail Pattern

// Master (List)
<StandardPage id="products" navigationTitle="Products">
  <List>
    {products.map(product => (
      <NavigationLink
        key={product.id}
        destination={() => <ProductDetail product={product} />}
        pageOptions={{ type: 'page' }}
      >
        <ProductRow product={product} />
      </NavigationLink>
    ))}
  </List>
</StandardPage>

// Detail
function ProductDetail({ product }) {
  return (
    <StandardPage
      id={`product-${product.id}`}
      navigationTitle={product.name}
      toolbarItems={<Button>Share</Button>}
    >
      <VStack>
        <Image src={product.image} />
        <Text>{product.description}</Text>
      </VStack>
    </StandardPage>
  )
}

Form with Save Button

<StandardPage
  id="edit"
  navigationTitle="Edit Profile"
  toolbarItems={
    <Button
      onClick={handleSave}
      disabled={!isValid}
    >
      Save
    </Button>
  }
>
  <Form onSubmit={handleSubmit}>
    <TextField label="Name" value={name} onChange={setName} />
    <TextField label="Email" value={email} onChange={setEmail} />
  </Form>
</StandardPage>

<StandardPage
  id="article"
  navigationTitle="Article"
  toolbarItems={
    <HStack spacing={12}>
      <Button onClick={handleBookmark}>
        <Text>🔖</Text>
      </Button>
      <Button onClick={handleShare}>
        <Text>Share</Text>
      </Button>
    </HStack>
  }
>
  <ScrollView>
    <Text>{articleContent}</Text>
  </ScrollView>
</StandardPage>

Styling

NavigationBar uses CSS variables for theming. You can customize colors:

:root {
  --sw-color-blue: #007AFF; /* Back button color */
  --sw-color-background-primary: #FFFFFF; /* Navigation bar background */
  --sw-color-separator: #C6C6C8; /* Bottom border */
}

Best Practices

Keep titles concise: Navigation bar titles should be short and descriptive
Use toolbar for actions: Place action buttons in toolbarItems, not in page content
Limit toolbar items: Too many toolbar items can clutter the navigation bar
Consistent navigation: Use navigationTitle consistently across related pages
Accessibility: Ensure toolbar buttons have proper labels for screen readers

StandardPage - Container that uses NavigationBar
NavigationStack - Manages navigation hierarchy
NavigationLink - Triggers navigation
Button - Used in toolbar items

Examples

Basic Usage

Automatic Back Button

With Toolbar Items

Integration with NavigationStack

API

Overview

Basic Usage

Automatic Back Button

Custom Back Button Behavior

Integration with NavigationStack

Props Reference

StandardPage Props (for NavigationBar)

NavigationBar Props (Internal)

Common Patterns

Master-Detail Pattern

Form with Save Button

Styling

Best Practices

On this page