--- tags: [SPMenu, service portal, menu, navigation, sp_instance_menu] --- # SPMenu Configures a Service Portal menu with hierarchical navigation items (`sp_instance_menu`). Menus define the navigation structure within a portal, supporting page links, knowledge base links, catalog items, filtered lists, and scripted menu items. SPMenu extends the SPInstance type. The properties below include inherited instance properties alongside menu-specific configuration. ## Signature ```typescript fluent SPMenu(config) ``` ## Parameters ### config `SPMenu` **Properties:** - **$id** (required): `string | number | ExplicitKey` - **$meta** (optional): `object` - **installMethod**: `'first install' | 'demo' | 'once'` Map a record to an output folder that loads only in specific circumstances. 'first install' - > 'unload', 'demo' -> 'unload.demo' - **active** (optional, default: true): `boolean` Whether this instance is rendered on the page. Set to `false` to hide the instance without deleting it. - **advancedPlaceholderDimensions** (optional, default: false): `boolean` Enables fine-grained control over placeholder width and height via `placeholderDimensions`. Only relevant when `asyncLoad` is `true`. - **asyncLoad** (optional, default: false): `boolean` Defers rendering of this widget until the async trigger condition is met. Use with `asyncLoadTrigger` to control when loading begins. - **asyncLoadDeviceType** (optional): `string` Comma-separated list of device types for which async loading is applied. - **asyncLoadTrigger** (optional, default: 'viewport'): `'viewport' | 'parallel'` Controls when async loading is triggered: - `'viewport'` — loads the widget when it is scrolled into the visible viewport. - `'parallel'` — loads the widget immediately in parallel with other page content. - **color** (optional, default: 'default'): `BootstrapColor` Bootstrap contextual color applied to the instance header band. Valid values: `'default'`, `'primary'`, `'success'`, `'info'`, `'warning'`, `'danger'`. - **column** (optional): `string | Record<'sp_column'>` Reference to the `sp_column` record this instance belongs to (used internally). - **css** (optional): `string` CSS scoped to this widget instance, applied in addition to the widget's own CSS. - **cssClass** (optional): `string` Additional CSS class name added to the instance wrapper element. - **glyph** (optional): `string` FontAwesome icon class (without the `fa-` prefix) shown alongside the instance title. - **id** (optional): `string` Unique string identifier for the instance record (`sp_instance.id`). - **items** (optional): `SPMenuItem[]` The menu items for the instance (maps to sp_rectangle_menu_item). **SPMenuItem properties:** - **$id** (required): `string | number | ExplicitKey` - **label** (required): `string` — Display text shown in the portal navigation. - **type** (optional, default: 'page'): `MenuType` — What the item links to. Values: `'page'`, `'url'`, `'sc_category'`, `'sc_cat_item'`, `'kb_topic'`, `'kb_article'`, `'kb_category'`, `'filtered'`, `'scripted'`. - **page** (optional): `string | Record<'sp_page'> | SPPage` — Portal page to navigate to. Required for page, catalog, and KB types. - **url** (optional): `string` — Destination URL (only for type `'url'`). - **kbTopic** (optional): `Topic` — Knowledge Base topic (`'Policies'`, `'Applications'`, `'General'`, `'FAQ'`, `'Desktop'`, `'News'`, `'Email'`). - **kbArticle** (optional): `string | Record<'kb_knowledge'>` — Specific knowledge article reference. - **kbCategory** (optional): `string | Record<'kb_category'>` — Knowledge Base category reference. - **scCategory** (optional): `string | Record<'sc_category'>` — Service Catalog category reference. - **catItem** (optional): `string | Record<'sc_cat_item'>` — Service Catalog item reference. - **script** (optional): `string | function` — Server-side script for dynamically generated child items (type `'scripted'`). - **childItems** (optional): `LeafMenuItem[]` — Nested child menu items (one level of nesting supported). - **order** (optional, default: 100): `number` — Sort order within the level. Lower values appear first. - **glyph** (optional): `string` — FontAwesome icon class (without the `fa-` prefix). - **roles** (optional): `(string | Role | Record<'sys_user_role'>)[]` — Restricts visibility to users with specified roles. - **filter** (optional): `string` — Encoded query string to filter records from `table` (type `'filtered'`). - **table** (optional): `TableName` — Table to query for filtered record items (type `'filtered'`). - **display1** (optional): `string` — Field from `table` to use as the primary label for filtered records. - **display2** (optional): `string` — Field from `table` to use as a secondary label for filtered records. - **displayDate** (optional): `'sys_created_on' | 'sys_updated_on' | ''` — Date field from `table` to display alongside each filtered record. - **urlTarget** (optional): `string` — HTML `` attribute for URL items (e.g. `'_blank'`). Only used when `type` is `'url'`. - **hint** (optional): `string` — Tooltip text shown on hover over the menu item. - **shortDescription** (optional): `string` — Admin-facing description of the menu item's purpose. - **color** (optional): `BootstrapColor` — Bootstrap contextual color (`'default'`, `'primary'`, `'success'`, `'info'`, `'warning'`, `'danger'`). - **active** (optional): `boolean` — Whether the menu item is rendered. Set to `false` to hide without deleting. - **condition** (optional): `string` — Encoded query condition evaluated server-side to control visibility - **order** (optional): `number` Sort order within the column. Lower values appear higher/earlier. - **placeholderConfigurationScript** (optional): `string` Server-side script that returns placeholder dimension config dynamically. Evaluated on page load before the widget is asynchronously loaded. - **placeholderDimensions** (optional): `JsonSerializable` JSON object specifying explicit width/height for the async placeholder. Only used when `advancedPlaceholderDimensions` is `true`. - **placeholderTemplate** (optional): `string` AngularJS HTML template rendered as the placeholder while async content loads. - **preservePlaceholderSize** (optional, default: false): `boolean` Maintains the placeholder element's height while async content is loading, preventing layout shift (CLS). Only relevant when `asyncLoad` is `true`. - **roles** (optional): `(string | Role | Record<'sys_user_role'>)[]` Restricts visibility of this instance to users with at least one of the specified roles. If empty, the instance is visible to all users who can access the page. - **shortDescription** (optional): `string` Brief admin-facing description of the instance's purpose. Not displayed to end users. - **size** (optional, default: 'md'): `SPInstanceSize` Visual size of the instance card in the portal designer. Valid values: `'sm'`, `'md'`, `'lg'`, `'xl'`. - **title** (optional): `string` Heading text displayed above the widget instance in the portal UI. - **url** (optional): `string` URL override applied to the instance link/title. - **widget** (optional): `string | Record<'sp_widget'> | SPWidget` The widget (`sp_widget`) to render at this position on the page. - **widgetParameters** (optional): `JsonSerializable` JSON key-value pairs passed to the widget's server and client scripts as `options`. Keys correspond to the widget's `optionSchema` property names. ## Examples ### sp-menu-basic ```typescript fluent // Source: packages/api/tests/service-portal/menu-plugin.test.ts import { SPMenu } from '@servicenow/sdk/core' export const BasicMenuExample = SPMenu({ $id: Now.ID['menu-id'], title: 'Test Menu', widget: '5ef595c1cb12020000f8d856634c9c6e', roles: ['admin', 'itil'], items: [ { $id: Now.ID['item-1'], type: 'page', label: 'Home', page: 'bf4aec5377014caca47b4845858ed506', }, ], }) ``` ### sp-menu-nested ```typescript fluent // Source: packages/api/tests/service-portal/menu-plugin.test.ts import { SPMenu } from '@servicenow/sdk/core' export const NestedMenuExample = SPMenu({ $id: Now.ID['menu-id'], title: 'Nested Menu', widget: '5ef595c1cb12020000f8d856634c9c6e', items: [ { $id: Now.ID['parent-item'], type: 'page', label: 'Parent', page: 'page-id-1', childItems: [ { $id: Now.ID['child-item'], type: 'kb_topic', label: 'Child', kbTopic: 'FAQ', page: 'page-id-2', }, ], }, ], }) ``` ### sp-menu-with-roles ```typescript fluent // Source: packages/api/tests/service-portal/menu-plugin.test.ts import { SPMenu } from '@servicenow/sdk/core' export const MenuWithRolesExample = SPMenu({ $id: Now.ID['menu-id'], title: 'Test Menu', widget: '5ef595c1cb12020000f8d856634c9c6e', roles: ['admin', 'itil'], active: true, size: 'md', color: 'default', order: 1, items: [ { $id: Now.ID['item-1'], type: 'page', label: 'Home', page: 'page-sys-id', order: 100, active: true, glyph: 'empty', color: 'default', }, ], }) ```