# Nav Bar
> A responsive, horizontal navigation bar designed for primary app navigation.
## Import
```js
import { NavBar } from '@gemini-suite/vera-react';
// you may also access NavBar's context via hook:
// import { useNavBarContext } from '@gemini-suite/vera-react';
```
NavBar is a compound component that consists of multiple parts.
- `Navbar.Root`: A container for all the parts of the nav bar.
- `Navbar.Item`: An item for a single action.
- `Navbar.ItemLabel`: An optional wrapper for item's textual label.
## Examples
### Basic
`NavBar` is a horizontal navigation bar that should be used to move between major areas of your application.
To alternate among related views within the same context, consider using [Tabs
component](/components/tabs) instead.
It is a responsive component that adapts to the available horizontal space.
When there is not enough space, nav bar items that don't fit will be added into an overflow disclosure menu.
The active item will remain visible to communicate the current context to the user.
Resize preview box below to notice responsive behavior of the component.
```jsx resizable=true
{'Home'}{'Dashboard'}{'Statistics'}{'Analytics'}{'Deployments'}
```
### Sizes
`NavBar` comes in two sizes: `medium` and `small`. By default, it uses `medium` size.
```jsx resizable=true
{'Dashboard'}{'Portfolio'}{'Market'}{'Capacity'}{'Trade results'}{'Dashboard'}{'Portfolio'}{'Market'}{'Capacity'}{'Trade results'}
```
### Controlled state
By default `NavBar` works in an uncontrolled way, managing its own state internally. Use `defaultActiveItem` prop to set the initial active item.
If you need to control the active item state, you should pass your own state to `activeItem` prop. `onActiveItemChange` handler is called when the active item changes, allowing you to sync state.
```jsx resizable=true
() => {
const [activePage, setActivePage] = React.useState('home');
return (
{'Home'}{'Bidding'}{'Trade results'}{'Insights'}
);
};
```
### Decorators
Use `startElement` and `endElement` props to add custom elements to the start and end of the `NavBar.Item`.
These are useful for providing an [Icon](/components/svg-icon) that visually represents and supports the item or adding a [Label](/components/label) to the item.
When item's text is not a direct children of `NavBar.Item`, you should wrap it with `NavBar.ItemLabel`. It is responsible for rendering a visibly hidden "copy" of the item text in bold, reserving box space for when text becomes bold in active state.
```jsx resizable=true
}>
{'Home'}
}>
{'Widgets'}
}>
{'Map'}
}
endElement={
}
>
{'Inbox'}
}>
{'Settings'}
}
>
{'Finance reports'}
```
### Disabled items
You can disable an item by passing `isDisabled` prop. Disabled items are not focusable and cannot be activated.
```jsx resizable=true
}>
{'Dashboard'}
} isDisabled>
{'Map'}
}>
{'Editor'}
}
isDisabled
>
{'Alerts'}
}>
{'Graphs'}
}>
{'Users management'}
```
### With app frame
Use `NavBar` with [App Frame component](/components/app-frame) to provide the structure for the application navigation.
`NavBar` should be placed below the application header and directly above the content it affects.
```jsx resizable=true
{'Product Name'}}>
{'Dashboard'}
}>
{'Map'}
}>
{'Editor'}
}>
{'Alerts'}
}>
{'Graphs'}
}
>
{'Users management'}
{'App view'}
```
### With fixed item
You can use `fixedStartItem` or `fixedEndItem` prop to render a fixed item to the left or right side of the nav bar. This item remains visible and accessible at all times, even if the rest of the navigation items overflow.
```jsx resizable=true
}
>
{'Configuration'}
}
>
}>
{'Home'}
}>
{'Reporting'}
}>
{'Widgets'}
}>
{'Stats'}
```
### With routing
If you need to use the `Link` component provided by your routing package (e.g. [React Router](https://reactrouter.com/en/main) or [Next.js](https://nextjs.org/docs/api-reference/next/link)), it's recommended to compose it with `NavBar.Item`:
```jsx
import { Link, useLocation } from 'react-router-dom';
import { NavBar } from '@gemini-suite/vera-react';
const routes = [
{
to: '/',
label: 'Home',
iconName: 'home'
},
{
to: '/dashboard',
label: 'Dashboard',
iconName: 'layout'
},
{
to: '/map',
label: 'Map',
iconName: 'globe2'
}
];
function App() {
const location = useLocation();
const [activeItem, setActiveItem] = useState(() => location.pathname);
return (
{routes.map(({ to, label, iconName }) => (
}
>
{label}
))}
);
}
```
---
## Accessibility
NavBar is `
The active item is conveyed to assistive technologies using the `aria-current` attribute.
Each item can be reached using the Tab key and activated by using the Enter key.
---
## API Reference
### Navbar.Root
| Name | Type | Default | Description | Required |
| -------------------- | ---------------------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. | |
| `defaultActiveItem` | `string` | | The id of the initial active item when nav bar is first rendered. Use when you do not need to control active item id. | |
| `activeItem` | `string` | | The controlled id of the item that should be active. Use in conjunction with `onActiveItemChange`. | |
| `onActiveItemChange` | `(id: string) => void` | | Event handler called when the active item id changes. | |
| `size` | `"medium" \| "small"` | `"medium"` | The size of the nav bar. | |
| `fixedStartItem` | `React.ReactElement` | | Fixed item to be rendered to the left side of thenav bar, before the list of items that can overflow. | |
| `fixedEndItem` | `React.ReactElement` | | Fixed item to be rendered to right side of the nav bar, after the list of items that can overflow. | |
| `moreMenuLabel` | `string` | `"More"` | Content of the overflow menu button tooltip. | |
### Navbar.Item
| Name | Type | Default | Description | Required |
| -------------- | --------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as` | `keyof JSX.IntrinsicElements \| React.ComponentType` | `button` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node. For more details, read our [Composition](/get-started/composition#polymorphism) guide. | |
| `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries or variants. | |
| `id` | `string` | | A unique identifier for the item. | Yes |
| `isDisabled` | `boolean` | | When `true`, the item will be disabled, preventing the user from interacting with it. | |
| `startElement` | `React.ReactElement` | | `ReactElement` to render to the left of the item's children. | |
| `endElement` | `React.ReactElement` | | `ReactElement` to render to the right of the item's children. | |
### Navbar.ItemLabel
| Name | Type | Default | Description | Required |
| ----- | --------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `as` | `keyof JSX.IntrinsicElements \| React.ComponentType` | `span` | Change the component to a different HTML tag or custom component. This will merge the original component props with the props of the supplied element/component and change the underlying DOM node. For more details, read our [Composition](/get-started/composition#polymorphism) guide. | |
| `css` | `StitchesCss` | | Apply styles directly to a component in a similar way how you would define inline styles. Vera uses [Stitches](https://stitches.dev/) under the hood with a fully-typed API and support for features like tokens, media queries, or variants. | |