Action Menu API

Registering Custom Categories

Add new buttons to the action menu:

Hooks.once("stylish-action-hud.apiReady", (api) => {
  api.registerActionMenuCategory({
    id: "my-custom-category",
    label: "Quick Actions",
    icon: "fa-solid fa-bolt",
    type: "submenu",
    cssClass: "btn-quick-actions",
  }, {
    priority: 50,
    source: "my-module",
    override: false,  // Set true to replace existing category with same id
    isCompatible: ({ actor }) => {
      // Only show for player characters
      return actor.type === "character";
    },
  });
});

Category Definition Properties

Category Types

• submenu: Opens a submenu panel when clicked
• sheet: Opens the character sheet
• system: Executes a system action immediately (via executeAction)

Registering Custom Submenus

Provide custom data for a submenu:

Hooks.once("stylish-action-hud.apiReady", (api) => {
  api.registerActionMenuSubMenu(
    "my-custom-category",  // Category ID to attach to
    async (actor, categoryId) => {
      // Provider function - returns submenu data
      return {
        title: "Quick Actions",
        hasTabs: true,
        hasSubTabs: false,
        items: {
          "combat": [
            { id: "action-1", name: "Attack", img: "icons/svg/sword.svg" },
            { id: "action-2", name: "Defend", img: "icons/svg/shield.svg" },
          ],
          "utility": [
            { id: "action-3", name: "Rest", img: "icons/svg/sleep.svg" },
          ],
        },
        tabLabels: {
          "combat": "Combat",
          "utility": "Utility",
        },
      };
    },
    {
      priority: 10,
      source: "my-module",
    }
  );
});

Submenu Data Structure

{
  title: "Menu Title",
  theme: "blue",           // Optional: "blue", "red", "green", etc.
  hasTabs: true,           // Enable tab navigation
  hasSubTabs: false,       // Enable sub-tab (sidebar) navigation

  // Items organized by tab
  items: {
    "tab-key": [
      {
        id: "item-id",
        name: "Item Name",
        img: "path/to/image.png",
        cost: "1 Action",           // Optional
        description: "Description", // Optional
        isHeader: false,            // If true, renders as section header
        isFavorite: false,          // Star indicator
        favoritable: true,          // Optional: set false to hide the favorite star on this row (v2.5.6+)
        isPersonal: false,          // Personal item indicator
        uses: { value: 3, max: 5 }, // Optional usage display
      },
      // ... more items
    ],
    // ... more tabs
  },

  tabLabels: {
    "tab-key": "Tab Display Name",
  },

  // For hasSubTabs: true
  subTabLabels: {
    "tab-key": {
      "subtab-key": "SubTab Display Name",
    },
  },
}

Hiding the favorite star (v2.5.6+)

Every submenu item shows a favorite star by default, and clicking it adds the item to Quick Slots. Set favoritable: false on an item to remove the star and its toggle.

Use this for rows that are not backed by a real Foundry Item, such as ability checks, saving throws, and rest actions. Quick Slots resolve a favorite back to an actor Item or macro, so a synthetic action id cannot become a working Quick Slot. Hiding the star keeps the row from showing a control that would do nothing in play.

items: [
  { id: "save-fort", name: "Fortitude Save", img: "icons/svg/shield.svg", favoritable: false },
  { id: "check-str", name: "Strength Check", img: "icons/svg/upgrade.svg", favoritable: false },
]

Items that leave out favoritable keep the star, so existing menus are unchanged.