# MenuList

A reusable `role="menu"` body for menu items, groups, and separators.

## Usage

Use inside `Popover` / `ContextMenu`, or standalone; fill with `MenuItem` / `MenuGroup` / `MenuSeparator`.
```svelte
<MenuList {...props}>
  <MenuItem {...props}>Item</MenuItem>
</MenuList>
```

## Anatomy

The `class` attribute values represent part names. Other attributes represent their corresponding props.

```svelte
<div class="whole" {...rest} role="menu" tabindex="-1" aria-orientation={orientation}>
  {#if children}
    {children}
  {:else if items}
    <MenuItem>{label}</MenuItem>
    <MenuSeparator />
  {/if}
</div>
```

Reusable `role="menu"` body. It reads an optional `MenuContainerContext` for `open`, `close`, `variant`, and `styling`; standalone usage still renders and navigates, while `close()` is a no-op without a container. When the container opens, the first enabled item is focused after `tick()`.

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `children` | `Snippet` | - | Menu content; wins over `items` when both are given |
| `items` | `MenuItemData[]` | - | Data-mode sugar for rendering items and separators; ignored when `children` is present |
| `orientation` | `<enum>` | `"vertical"` | Sets keyboard direction and `aria-orientation` |
| `attach` | `Attachment` | - | Svelte attachment on the root list |
| `element` | `HTMLDivElement` | - | Bindable root element |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | List variant unless a menu container context is present; container context wins |
Other `HTMLAttributes` are passed to `<div>` via rest props; `class` is merged onto the root.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

No automatic switching.

### Default Class Name

`svs-menu-list`

## Behavior

Reusable `role="menu"` body. It reads an optional `MenuContainerContext` for `open`, `close`, `variant`, and `styling`; standalone usage still renders and navigates, while `close()` is a no-op without a container. When the container opens, the first enabled item is focused after `tick()`.

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `ArrowDown` / `ArrowUp` | With `orientation="vertical"` (default), moves focus to the next or previous enabled menu item, wrapping at the ends |
| `ArrowRight` / `ArrowLeft` | With `orientation="horizontal"`, moves focus to the next or previous enabled menu item, wrapping at the ends |
| `Home` / `End` | Moves focus to the first or last enabled menu item |
| `Tab` | Closes the containing menu |
| Printable character | Moves focus by type-ahead to the next enabled item whose text starts with the typed buffer |
The type-ahead buffer resets after 500 ms. When a containing menu opens, focus moves to the first enabled item.

### ARIA Roles and Attributes

The component applies these automatically:

- Root (`whole`): `role="menu"`, `aria-orientation`, and `tabindex="-1"`.
- Items with `aria-disabled="true"` are skipped by keyboard navigation.

`MenuList` looks for descendant `role="menuitem"` elements; `MenuItem` provides that role. Provide an accessible name for standalone menus when surrounding context does not label the menu, by passing `aria-label` or `aria-labelledby` through rest props.

## Exports

### Types

```ts
interface MenuListProps extends Omit<HTMLAttributes<HTMLDivElement>, "children" | "role"> {
  children?: Snippet<[string]>; // Snippet<[variant]>; wins over `items` when both given
  items?: MenuItemData[]; // data-mode sugar; ignored when `children` is present
  orientation?: "horizontal" | "vertical"; // ("vertical")
  attach?: Attachment<HTMLDivElement>;
  element?: HTMLDivElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // (VARIANT.NEUTRAL); container context wins when present
  // other HTMLAttributes are passed to <div> via ...rest; `class` is merged onto root
  // role, tabindex, aria-orientation, and keyboard handling are component-owned
}
type MenuListReqdProps = never;
type MenuListBindProps = "element";
interface MenuContainerContext extends SVSContext {
  get open(): boolean;
  close(): void;
}
type MenuItemData = MenuItemEntry | MenuSeparatorData;
type MenuItemEntry = {
  label: string | Snippet<[string]>;
  onselect?: (ev: MouseEvent) => void;
  disabled?: boolean;
};
type MenuSeparatorData = { separator: true };
```

### Others

No additional exports are available.

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=MenuListBasic.svelte
<script lang="ts">
  import { MenuItem, MenuList, MenuSeparator } from "svseeds";

  const styling = {
    whole: "flex min-w-44 flex-col gap-1 rounded-md border bg-white p-1 shadow-lg dark:bg-black",
  };
  const childStyle1 = {
    whole:
      "rounded-sm px-2 py-1 text-left text-sm hover:bg-gray-100 focus:bg-gray-100 focus:outline-hidden dark:hover:bg-gray-800 dark:focus:bg-gray-800",
  };
  const childStyle2 = {
    whole: "my-1 border-t border-gray-200 dark:border-gray-800",
  };
</script>

<MenuList {styling}>
  <MenuItem styling={childStyle1}>Profile</MenuItem>
  <MenuItem styling={childStyle1}>Settings</MenuItem>
  <MenuSeparator styling={childStyle2} />
  <MenuItem styling={childStyle1}>Sign out</MenuItem>
</MenuList>
```
### With Interactive Variant

**Code**

```svelte src=MenuListPract.svelte
<script lang="ts">
  import { MenuItem, MenuList, MenuSeparator } from "svseeds";

  let { variant = $bindable() } = $props();
  const variantStyle1 = {
    neutral: "border-gray-400",
    active: "border-teal-500",
    inactive: "border-red-500",
    blue: "border-blue-500",
    yellow: "border-yellow-500",
    sky: "border-sky-500",
  };
  const variantStyle2 = {
    neutral: "hover:bg-gray-100 focus:bg-gray-100 dark:hover:bg-gray-800 dark:focus:bg-gray-800",
    active: "hover:bg-teal-100 focus:bg-teal-100 dark:hover:bg-teal-900 dark:focus:bg-teal-900",
    inactive: "hover:bg-red-100 focus:bg-red-100 dark:hover:bg-red-900 dark:focus:bg-red-900",
    blue: "hover:bg-blue-100 focus:bg-blue-100 dark:hover:bg-blue-900 dark:focus:bg-blue-900",
    yellow: "hover:bg-yellow-100 focus:bg-yellow-100 dark:hover:bg-yellow-900 dark:focus:bg-yellow-900",
    sky: "hover:bg-sky-100 focus:bg-sky-100 dark:hover:bg-sky-900 dark:focus:bg-sky-900",
  };
  const variantStyle3 = {
    neutral: "border-gray-200 dark:border-gray-800",
    active: "border-teal-200 dark:border-teal-900",
    inactive: "border-red-200 dark:border-red-900",
    blue: "border-blue-200 dark:border-blue-900",
    yellow: "border-yellow-200 dark:border-yellow-900",
    sky: "border-sky-200 dark:border-sky-900",
  };
  const styling = {
    whole: {
      base: "flex min-w-44 flex-col gap-1 rounded-md border bg-white p-1 shadow-lg dark:bg-black",
      ...variantStyle1,
    },
  };
  const childStyle1 = {
    whole: {
      base: "rounded-sm px-2 py-1 text-left text-sm focus:outline-hidden",
      ...variantStyle2,
    },
  };
  const childStyle2 = {
    whole: {
      base: "my-1 border-t",
      ...variantStyle3,
    },
  };
</script>

<MenuList {variant} {styling}>
  <MenuItem styling={childStyle1}>New file</MenuItem>
  <MenuItem styling={childStyle1}>Duplicate</MenuItem>
  <MenuSeparator styling={childStyle2} />
  <MenuItem styling={childStyle1}>Archive</MenuItem>
</MenuList>
```
### With Data Items

**Code**

```svelte src=MenuListData.svelte
<script lang="ts">
  import { MenuList } from "svseeds";
  import type { MenuItemData } from "svseeds";

  let selected = $state("None");
  const items: MenuItemData[] = [
    { label: "Create", onselect: () => (selected = "Create") },
    { label: "Rename", onselect: () => (selected = "Rename") },
    { separator: true },
    { label: "Archive", onselect: () => (selected = "Archive") },
    { label: "Locked", disabled: true },
  ];
  const myProps = {
    items,
    class: "menu-list-data flex min-w-44 flex-col gap-1 rounded-md border bg-white p-1 shadow-lg dark:bg-black",
  };
</script>

<div class="flex flex-col items-center gap-3">
  <MenuList {...myProps} />
  <p class="text-sm">Selected: {selected}</p>
</div>

<style>
  :global(.menu-list-data .svs-menu-item.whole) {
    border-radius: 0.125rem;
    padding: 0.25rem 0.5rem;
    text-align: left;
    font-size: 0.875rem;
  }
  :global(.menu-list-data .svs-menu-item.whole:hover),
  :global(.menu-list-data .svs-menu-item.whole:focus) {
    background: color-mix(in oklab, currentColor 8%, transparent);
    outline: none;
  }
  :global(.menu-list-data .svs-menu-item.whole[aria-disabled="true"]) {
    opacity: 0.5;
  }
  :global(.menu-list-data .svs-menu-separator.whole) {
    margin: 0.25rem 0;
    border-top: 1px solid color-mix(in oklab, currentColor 15%, transparent);
  }
</style>
```