User Guide

Neo Shelf - User Guide

Neo Shelf is a replacement for Maya's internal shelf system, offering fully customizable, dockable shelf panels with advanced features like configurable mouse triggers, multiple shelves support, multi edit, and drag-and-drop reordering.

Key Differences from Maya Shelf

Neo Shelf is not just a visual replacement for Maya's shelf system. It introduces features that Maya's native shelves do not support:

Feature	Maya Native	Neo Shelf
View multiple shelves at once	No (tabbed, one visible at a time)	Yes (dock separately or together)
Custom background color per shelf	No	Yes
Customizable mouse triggers	No	Yes (assign actions to LMB/RMB clicks, shift+click, holds, double-clicks)
Icon tinting	No	Yes (colorize white SVGs with any color)
External icon browser	Limited	Yes (add your own icon folder paths)
Layout modes	Horizontal only	Flow, Horizontal, Vertical
Horizontal alignment	Left, Right	Left, Center, Right
Edit multiple buttons at once	No	Yes (multi-select in manager)
Drag to reorder	No	Yes (middle mouse drag)
Close without losing data	No (shelf deleted)	Yes (data preserved, reopen anytime)
Secondary command	Double-click only	Configurable trigger
Submenu trigger	Right-click only	Configurable (default: hold)

Installation

Copy the neo_shelf folder to your Maya scripts directory:

C:\Users\<username>\Documents\maya\<version>\scripts\

Add the following line to your userSetup.mel file:

source "C:/Users/<username>/Documents/maya/<version>/scripts/neo_shelf/menuItemToShelf.mel";
evalDeferred("python(\"import neo_shelf;\nfrom neo_shelf import core, widgets, manager\")");

Replace <username> and <version> with your actual values.

Restart Maya or source the MEL file manually.

Quick Start

Open Maya's Script Editor and run:

import neo_shelf
neo_shelf.show()

This opens the shelf manager window, letting you create your first shelves or import existing ones.

Creating Shelf Panels

From the Manager

Open the manager with neo_shelf.show() (You will only need to do this once, then you can open shelf manager window from any existing shelf.)
Click the New button in the Shelves column
Enter a name for your new shelf
Click Open to create a dockable panel

You can also import existing Maya shelves

Understanding the Active Shelf

In Maya's native shelf system, only one shelf tab is visible at a time. When you Ctrl+Shift+Click a menu item, Maya knows exactly which shelf to add the button to because there is only one shelf on screen.

Neo Shelf is different. You can have multiple shelf panels open simultaneously, docked in various locations or floating as separate windows. This raises a question: when you Ctrl+Shift+Click a menu item, which shelf should receive the new button?

The answer is the active shelf. Neo Shelf tracks which shelf panel you last clicked on and marks it as active. The active shelf is indicated by a colored border (the highlight color, which you can customize per shelf).

How it works:

Click anywhere on a shelf panel to make it the active shelf
A colored border appears around the panel
Any Ctrl+Shift+Click on a menu item adds the button to this active shelf
Clicking a different shelf panel changes the active shelf

Tips:

If you only have one shelf open, it is automatically the active shelf
You can hide the active highlight border per shelf if you find it distracting (see Hide Highlight option in the manager)
The active shelf is remembered between Maya sessions

Adding Buttons

Method 1: Ctrl+Shift+Click (Recommended)

Click on a shelf panel to make it active (blue border appears)
Hold Ctrl+Shift and click any Maya menu item
The button is automatically added to the active shelf

Method 2: Drag from Script Editor

Select code in Maya's Script Editor
Middle-mouse drag the selection onto a shelf panel
A new button is created with the selected code as its command

Method 3: From the Manager

Open the manager
Select a shelf in the left column
Click the Add button in the Buttons column
Configure the button properties in the options panel

The Manager UI

The manager is a unified interface for editing shelves and buttons. Open it with:

import neo_shelf
neo_shelf.show()

Or right-click any button on a shelf panel.

Layout

+------------------+------------------------+
|     Shelves      |        Buttons         |
|   (list view)    |   (multi-select list)  |
+==================+========================+
|       Context-Sensitive Options Panel     |
+-------------------------------------------+
|  Refresh All | Import | Triggers | Help   |
+-------------------------------------------+

Shelf Options

When a shelf is selected:

Name: Display name for the shelf
Icon Size: Size of all buttons in this shelf (minimum 35px)
BG Color: Custom background color for the shelf panel
Highlight Color: Border color when this shelf is active (see Understanding the Active Shelf)
Hide Highlight: Disable the active border highlight for this shelf
Alignment: Button alignment - Left, Center, or Right (only enabled in horizontal layout)
Layout: Flow, Horizontal, or Vertical

Button Options

When a button is selected, four tabs appear:

Main Tab

Name, Icon, Label, Tooltip
Icon Tint (colorize icons)
Background and label colors

Command Tab

Primary command (Python or MEL)

Secondary Command Tab

Command executed on Shift+Click (by default)

Submenus Tab

Manage popup menu items for hold-click

Multi-Selection Editing

You can select multiple buttons in the manager (Ctrl+Click or Shift+Click) to edit them together:

Color changes apply to all selected buttons
Duplicate, Delete, Transfer, and Copy actions work on all selected
Command tabs are disabled during multi-selection (commands must be edited individually)

Layout Modes

Each shelf can use one of three layout modes:

Mode	Description
Flow	Buttons wrap to new lines based on panel width. Best for responsive layouts.
Horizontal	Single row of buttons. Supports alignment: Left, Center, or Right.
Vertical	Single column of buttons stacked top to bottom.

Change the layout in the manager's shelf options panel.

Alignment (Horizontal Mode Only)

When using horizontal layout, you can align buttons to the left, center, or right of the panel. Maya's native shelf only supports left and right alignment. Neo Shelf adds center alignment for symmetrical toolbar layouts.

Configuring Triggers

Neo Shelf allows you to customize which mouse actions trigger which behaviors.

Opening Trigger Settings

Open the manager
Click Set Trigger Mechanism at the bottom

Available Actions

Action	Default Trigger
Execute Main Command	Left Click
Execute Secondary Command	Shift + Left Click
Open Manager Panel	Right Click
Open Popup Menu	Left Hold (300ms)

Available Triggers

LMB Single Click
Shift + LMB Click
LMB Hold (300ms)
RMB Single Click
LMB Double Click
Not Set (disable action)

Each trigger can only be assigned to one action.

Importing Maya Shelves

You can import existing Maya shelf files (.mel) into Neo Shelf:

Open the manager
Click Import Native Shelf
Navigate to Maya's shelf directory (defaults to prefs/shelves)
Select one or more .mel shelf files
Click Open

Imported data includes:

Button icons and labels
Commands (Python and MEL)
Submenus
Color overrides
Annotations/tooltips

Note: Import is a one-time copy. Changes to the original Maya shelf will not sync.

Button Customization

Icon Options

Internal Icons: Browse Maya's built-in icon library through a visual picker
External Icons: Add your own icon folders via the icon chooser. Paths are saved and persist between sessions.
Icon Tint: Colorize icons with any RGB color. Useful for white SVG icons that need to match your color scheme.

Label Options

Labels appear as overlays at the bottom of button icons:

Label Text: The text to display
Label Text Color: Text color (RGB)
Label BG Color: Background color with opacity (RGBA)

Submenus

Create popup menus that appear on hold-click:

Select a button in the manager
Go to the Submenus tab
Add items with labels and commands
Add separators to organize items

Keyboard Shortcuts and Mouse Actions

Action	Result
Ctrl+Shift+Click (on Maya menu item)	Add menu item to active shelf
Middle Mouse Drag (on shelf button)	Reorder buttons within a shelf
Left Click (on shelf panel)	Make this shelf active
Right Click (on shelf button)	Open manager with button selected
Close panel (X button)	Shelf data is preserved, reopen anytime from manager

Configuration Files

Neo Shelf stores its configuration in:

C:\Users\<username>\Documents\maya\<version>\scripts\neo_shelf_config.json

This file contains:

All shelf definitions and button data
Global settings (default icon size, triggers)
Panel registry (which panels are open)
Custom icon folder paths

Troubleshooting

Panels not appearing after Maya restart

Panels should restore automatically. If not, recreate them:

import neo_shelf
neo_shelf.create_panel("ShelfName")

Buttons not executing commands

Check the command in the manager's Command tab
Verify Python/MEL radio button is correct
For Python, ensure proper indentation

Refreshing panels after code changes

import neo_shelf
neo_shelf.refresh()

Full module reload (development)

import sys
import neo_shelf
module_names = list(sys.modules.keys())

for l in module_names:
    if 'neo_shelf' in l:
        print(f"Deleting: {l}")
        del sys.modules[l] 
import neo_shelf
from neo_shelf import core, widgets, manager
neo_shelf.show()  # Opens manager (no argument)

View current configuration

from neo_shelf import core
import json
print(json.dumps(core.load_config(), indent=2))

API Reference

import neo_shelf

# Show manager or specific shelf
neo_shelf.show()
neo_shelf.show("ShelfName")

# Create and manage panels
neo_shelf.create_panel("ShelfName")
neo_shelf.close_panel("neoShelf_ShelfName")

# Active shelf
neo_shelf.get_active_shelf()
neo_shelf.set_active_shelf("ShelfName")

# Refresh all panels
neo_shelf.refresh()

For bug reports and feature requests, visit the GitHub repository.