--- title: Navigation regions editUrl: https://github.com/Cratis/Screenplay/edit/main/Documentation/screenplay/navigation.md description: Declare the topbar and sidebar navigation regions of a Screenplay application shell and how each module inherits or overrides them. lastUpdated: 2026-10-19T00:00:00.000Z --- The application shell has two navigation regions: a **topbar** and a **sidebar**. A `layout` declares what the application puts in them. A `module` states how it relates to them - it inherits the application's items, extends them with its own, or overrides them. The blocks are the Screenplay form of Scene's `NavigationModel`, so a navigation authored here is the one the designer shows, Stage renders and Studio round-trips. ## At application level Regions are blocks inside a [`layout`](/screenplay/templates/), next to its slots. The application's regions have no mode: the application is the base. ```screenplay layout AppShell category application topbar navigation contributes Navigation content side navigation topbar logo image "/assets/acme.svg" title "Acme" item sales title "Sales" icon receipt target Sales item support title "Support" target Support.Tickets slot content navigation sidebar item sales title "Sales" target Sales item orders title "Orders" target Sales.Orders item returns title "Returns" target Sales.Orders.Returns slot side item help title $strings.nav.help target Support module Sales feature Orders feature Returns module Support feature Tickets ``` - `navigation topbar` and `navigation sidebar` each appear at most once per layout. `navigation contributes Navigation` is still a slot declaration; `navigation` followed by `topbar` or `sidebar` is a region. - `logo image "" title ""` is the application's logo. It is declared once, in a layout - never in a module (`PLAY0744`). - `item title "" [icon ] [target [.]] [slot ]` is one item. The id is unique within the region (`PLAY0747`). The title is a quoted string or a `$strings.` token, see [Internationalization](/screenplay/internationalization/). `icon` takes an identifier or a quoted string. - `target` names a module, or a module and a feature path (`Sales.Orders.Returns` for a nested feature). A module target goes to the module's first feature. An item with no target must have sub-items (`PLAY0748`). - `slot` names the layout slot the target renders into. Without it the target renders into the layout's primary content slot. A slot no layout declares is `PLAY0749`. - In the sidebar, an item may nest further `item` lines: top-level items target modules and sub-items target features. Topbar items do not nest (`PLAY0746`). - `button title "" [slice ..] [emphasis primary|secondary|quiet] [icon ]` is an application-level toolbar button in `navigation topbar`. It has the grammar and the checks of a [screen toolbar button](/screenplay/screens/): the slice is a State Change slice (`PLAY0761` to `PLAY0765`), and the button opens that slice's task dialog over whichever page the user is on. An indented `authorize ` line under the button limits who sees it; it takes the same policy expression as `authorize` on a command. Buttons are not allowed in `navigation sidebar` (`PLAY0741`). In a module, `navigation topbar extends` adds buttons after the application's, `overrides` shows only the module's own, and `inherits` keeps the application's, exactly as for items. ## At module level A module declares a block only for a region it changes. A region it does not mention **inherits** the application's items. ```screenplay layout AppShell category application content navigation sidebar item sales title "Sales" target Sales item support title "Support" target Support module Sales navigation sidebar extends item customers title "Customers" icon people target Sales.Customers navigation topbar overrides item orders title "Orders" target Sales.Orders feature Orders feature Customers module Support feature Tickets ``` | Written | Effective items in the module | | --- | --- | | no block | The application's items (inherits). | | `navigation inherits` | The application's items. The explicit form of the default; it lists no items (`PLAY0745`). | | `navigation extends` | The application's items, followed by the module's own. | | `navigation overrides` | The module's own items only. An override with no items leaves the region empty and warns (`PLAY0752`). | - Each region has its own mode; `topbar` and `sidebar` are independent. - A module's own items may only target that module (`PLAY0750`). To link elsewhere, put the item in the layout. - An extending module's item ids must not repeat the application's (`PLAY0747`). - Targeting a module with no feature warns (`PLAY0751`). A layout region that states a mode is rejected with `PLAY0745`. ## `navigation` and `contribute to Navigation` [`contribute to Navigation`](/screenplay/contributions/) stays valid. It is how a feature adds one flat item to a slot that `contributes Navigation`. A region block describes the region's own item tree with hierarchy, targets, slots and inheritance. The two are independent: neither generates the other, and a layout can use both. A new application models its navigation with regions. ## Checks and the TypeScript compiler The C# compiler checks the regions against the modules, features and layout slots the document declares and reports [`PLAY0740`-`PLAY0752`](/screenplay/diagnostics/#navigation-regions); the findings mirror Scene's `navTargetMissing`, `navSlotUnknown`, `navDuplicateId`, `navTargetOutOfScope` and `navModuleWithoutFeatures`. The TypeScript compiler recognizes `navigation` in a module and skips it whole, as it skips layouts, so the checks are C#-only. Navigation blocks are authoring syntax: the executable model does not carry them, and Stage plans them from the syntax tree. Parser, printer and parser again keep every item, id, icon, slot, target and mode. The syntax tree carries `NavigationRegionSyntax` (on `LayoutSyntax` and `ModuleSyntax`), `NavigationItemSyntax`, `NavigationTargetSyntax` and `NavigationLogoSyntax`; see [AST compatibility](/screenplay/ast-compatibility/). ## Rename and move An item's `target` names a module or feature. Renaming or moving a module or feature that a navigation item targets is refused with an explicit message - rename or move it together with the `target` in coordinated typed edits. Declarations no item targets rename and move as usual. ## See also - [Layouts and templates](/screenplay/templates/) for the shell and its slots. - [UI profile](/screenplay/ui-profile/) for the `root template` that selects the shell the navigation regions live in. - [Contributions](/screenplay/contributions/) for the many-to-one `contribute to`. - [Screens capability matrix](/screenplay/screens-capability-matrix/).