# `PetalComponents.Menu`
[🔗](https://github.com/petalframework/petal_components/blob/v3.2.0/lib/petal_components/menu.ex#L1)

# `menu_group`

## Attributes

* `current_page` (`:atom`)
* `menu_items` (`:list`)
* `title` (`:string`)
* `js_lib` (`:string`) - javascript library used for toggling. Defaults to `"alpine_js"`. Must be one of `"alpine_js"`, or `"live_view_js"`.
* `on_toggle` (`Phoenix.LiveView.JS`) - Defaults to `%Phoenix.LiveView.JS{ops: []}`.

# `vertical_menu`

## Menu items structure

Menu items (main_menu_items + user_menu_items) should have this structure:

      [
        %{
          name: :sign_in,
          label: "Sign in",
          path: "/sign-in,
          icon: "hero-key",
        }
      ]

### Name

The name is used to identify the menu item. It is used to highlight the current menu item.

    <.sidebar_layout current_page={:sign_in} ...>

### Label

This is the text that will be displayed in the menu.

### Path

This is the path that the user will be taken to when they click the menu item.
The default link type is a live_redirect. This will work for non-live view links too.

#### Live patching

Let's say you have three menu items that point to the same live view. In this case we can utilize a live_patch link. To do this, you add the `patch_group` key to the menu item.

    [
      %{name: :one, label: "One", path: "/one, icon: "hero-key", patch_group: :my_unique_group},
      %{name: :two, label: "Two", path: "/two, icon: "hero-key", patch_group: :my_unique_group},
      %{name: :three, label: "Three", path: "/three, icon: "hero-key", patch_group: :my_unique_group},
      %{name: :another_link, label: "Other", path: "/other, icon: "hero-key"},
    ]

Now, if you're on page `:one`, and click a link in the menu to either `:two`, or `:three`, the live view will be patched because they are in the same `patch_group`. If you click `:another_link`, the live view will be redirected.

### Icons

The icon should match to a Heroicon (Petal Components must be installed).
If you have your own icon, you can pass a function to the icon attribute instead of an atom:

      [
        %{
          name: :sign_in,
          label: "Sign in",
          path: "/sign-in,
          icon: &my_cool_icon/1,
        }
      ]

Or just pass a string of HTML:

      [
        %{
          name: :sign_in,
          label: "Sign in",
          path: "/sign-in,
          icon: "<svg>...</svg>",
        }
      ]

## Nested menu items

You can have nested menu items that will be displayed in a dropdown menu. To do this, you add a `menu_items` key to the menu item. eg:

      [
        %{
          name: :auth,
          label: "Auth",
          icon: "hero-key",
          menu_items: [
            %{
              name: :sign_in,
              label: "Sign in",
              path: "/sign-in,
              icon: "hero-key",
            },
            %{
              name: :sign_up,
              label: "Sign up",
              path: "/sign-up,
              icon: "hero-key",
            },
          ]
        }
      ]

## Menu groups

Sidebar supports multi menu groups for the side menu. eg:

User
- Profile
- Settings

Company
- Dashboard
- Company Settings

To enable this, change the structure of main_menu_items to this:

    main_menu_items = [
      %{
        title: "Menu group 1",
        menu_items: [ ... menu items ... ]
      },
      %{
        title: "Menu group 2",
        menu_items: [ ... menu items ... ]
      },
    ]

## Attributes

* `menu_items` (`:list`) (required)
* `current_page` (`:atom`) (required)
* `title` (`:string`) - Defaults to `nil`.
* `js_lib` (`:string`) - javascript library used for toggling. Defaults to `"alpine_js"`. Must be one of `"alpine_js"`, or `"live_view_js"`.
* `on_toggle` (`Phoenix.LiveView.JS`) - additional JS commands to run when a submenu is toggled (LiveView.JS only). Defaults to `%Phoenix.LiveView.JS{ops: []}`.

# `vertical_menu_item`

## Attributes

* `current_page` (`:atom`)
* `path` (`:string`) - Defaults to `nil`.
* `icon` (`:any`) - Defaults to `nil`.
* `label` (`:string`)
* `name` (`:atom`) - Defaults to `nil`.
* `menu_items` (`:list`) - Defaults to `nil`.
* `all_menu_items` (`:list`) - Defaults to `nil`.
* `patch_group` (`:atom`) - Defaults to `nil`.
* `link_type` (`:string`) - Defaults to `"live_redirect"`.
* `js_lib` (`:string`) - javascript library used for toggling. Defaults to `"alpine_js"`. Must be one of `"alpine_js"`, or `"live_view_js"`.
* `on_toggle` (`Phoenix.LiveView.JS`) - Defaults to `%Phoenix.LiveView.JS{ops: []}`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*