@servicenow/sdk/docs/api/service-portal/spmenu-api.md

ServiceNow SDK

---
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<string>`

- **$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<string>`
  - **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 `<a target>` 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',
        },
    ],
})

```