> ## Documentation Index
> Fetch the complete documentation index at: https://lationscripts.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Modern UI - Radial

> Radial menu with hierarchical menus, progress rings, and status badges

## Quick Start

```lua theme={null}
exports.lation_ui:registerRadial({
    id = 'my_menu',
    items = {
        {
            label = 'Option 1',
            icon = 'user',
            onSelect = function()
                print('Option 1 selected')
            end
        },
        {
            label = 'Option 2',
            icon = 'car',
            onSelect = function()
                print('Option 2 selected')
            end
        }
    }
})

exports.lation_ui:addRadialItem({
    id = 'my_item',
    label = 'My Menu',
    icon = 'circle',
    menu = 'my_menu'
})
```

## Functions

<AccordionGroup>
  <Accordion title="registerRadial" icon="plus">
    Register a radial submenu with the specified configuration.

    ```lua theme={null}
    exports.lation_ui:registerRadial(radialData)
    ```

    **Parameters:**

    * `radialData` (table) - Radial menu configuration object (see [Registration Options](#registration-options))
  </Accordion>

  <Accordion title="addRadialItem" icon="circle-plus">
    Add one or more items to the global radial menu.

    ```lua theme={null}
    exports.lation_ui:addRadialItem(item) -- Single item
    exports.lation_ui:addRadialItem({item1, item2}) -- Multiple items
    ```

    **Parameters:**

    * `item` (table | table\[]) - Single item or array of items (see [Item Properties](#item-properties))
  </Accordion>

  <Accordion title="removeRadialItem" icon="circle-minus">
    Remove an item from the global radial menu.

    ```lua theme={null}
    exports.lation_ui:removeRadialItem(itemId)
    ```

    **Parameters:**

    * `itemId` (string) - Unique identifier of the item to remove
  </Accordion>

  <Accordion title="clearRadialItems" icon="trash">
    Clear all items from the global radial menu.

    ```lua theme={null}
    exports.lation_ui:clearRadialItems()
    ```
  </Accordion>

  <Accordion title="hideRadial" icon="eye-slash">
    Hide the radial menu.

    ```lua theme={null}
    exports.lation_ui:hideRadial()
    ```
  </Accordion>

  <Accordion title="disableRadial" icon="ban">
    Enable or disable the radial menu.

    ```lua theme={null}
    exports.lation_ui:disableRadial(state)
    ```

    **Parameters:**

    * `state` (boolean) - `true` to disable, `false` to enable
  </Accordion>

  <Accordion title="getCurrentRadialId" icon="question">
    Get the ID of the currently open radial menu.

    ```lua theme={null}
    local menuId = exports.lation_ui:getCurrentRadialId()
    ```

    **Returns:**

    * `menuId` (string | nil) - The ID of the currently open menu, or nil if no menu is open
  </Accordion>
</AccordionGroup>

## Configuration

### Registration Options

<ParamField path="id" type="string" required>
  Unique menu identifier
</ParamField>

<ParamField path="items" type="table" required>
  Array of menu items (see [Item Properties](#item-properties))
</ParamField>

### Item Properties

<ParamField path="id" type="string">
  Unique item identifier (required for global items)
</ParamField>

<ParamField path="label" type="string" required>
  Item display text
</ParamField>

<ParamField path="icon" type="string">
  FontAwesome icon class or image URL

  Supported image formats: `.png`, `.webp`, `.jpg`, `.jpeg`, `.gif`, `.svg`
</ParamField>

<ParamField path="iconColor" default="#9CA3AF" type="string">
  Icon color (hex or [CSS color name](https://htmlcolorcodes.com/color-names/))
</ParamField>

<ParamField path="iconAnimation" type="string">
  Icon animation type

  Available options: `'spin'`, `'spinPulse'`, `'spinReverse'`, `'pulse'`, `'beat'`, `'fade'`, `'beatFade'`, `'bounce'`, `'shake'`
</ParamField>

<ParamField path="iconAnimateOnHover" default="false" type="boolean">
  If `true`, icon only animates on hover instead of continuously
</ParamField>

<ParamField path="menu" type="string">
  Submenu ID to open
</ParamField>

<ParamField path="progress" type="number">
  Progress ring value (0-100)
</ParamField>

<ParamField path="progressColor" default="#3B82F6" type="string">
  Progress ring color (hex or [CSS color name](https://htmlcolorcodes.com/color-names/))
</ParamField>

<ParamField path="badge" type="number | string">
  Badge text or count

  <Note>
    Numbers greater than 99 display as "99"
  </Note>
</ParamField>

<ParamField path="badgeColor" default="#EF4444" type="string">
  Badge color (hex or [CSS color name](https://htmlcolorcodes.com/color-names/))
</ParamField>

<ParamField path="readOnly" default="false" type="boolean">
  Display only, no hover or click
</ParamField>

<ParamField path="keepOpen" default="false" type="boolean">
  Keep menu open after clicking
</ParamField>

<ParamField path="onSelect" type="function">
  Callback function executed when item is selected

  **Parameters:**

  * `currentMenu` (string | nil) - The current menu ID (or `nil` for global menu)
  * `itemIndex` (number) - The clicked item's index

  ```lua theme={null}
  onSelect = function(currentMenu, itemIndex)
  	print(currentMenu, itemIndex)
  end
  ```
</ParamField>

<Note>
  Press Z to open/close the global radial menu (*will only display when there is at least one item*)
</Note>

## Preview

<Frame>
  <img src="https://mintcdn.com/lationscripts/Ti0acW9JT3q4BC3Y/resources/modern-ui/components/radial/global-menu.webp?fit=max&auto=format&n=Ti0acW9JT3q4BC3Y&q=85&s=5e0c676b46cccd8cb5673e7b61b22337" alt="Radial Menu Global" width="907" height="907" data-path="resources/modern-ui/components/radial/global-menu.webp" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/lationscripts/Ti0acW9JT3q4BC3Y/resources/modern-ui/components/radial/player-submenu.webp?fit=max&auto=format&n=Ti0acW9JT3q4BC3Y&q=85&s=33caba42741b1a96e67b49ede7ef6529" alt="Radial Menu Submenu" width="907" height="907" data-path="resources/modern-ui/components/radial/player-submenu.webp" />
</Frame>

<Frame>
  <img src="https://mintcdn.com/lationscripts/Ti0acW9JT3q4BC3Y/resources/modern-ui/components/radial/examples-submenu.webp?fit=max&auto=format&n=Ti0acW9JT3q4BC3Y&q=85&s=002fb060330cc85ac7b3e3e4720b393d" alt="Radial Menu Submenu" width="907" height="907" data-path="resources/modern-ui/components/radial/examples-submenu.webp" />
</Frame>