Complete plugin reference & how-to guide.

The Tool Palette is a dockable WPF panel that registers as a native Revit pane. It aggregates all configured buttons from the active palette and presents them in a scrollable, searchable, tabbed interface. Multiple palettes can be configured and switched on demand, or automatically via Delegation.

Registers as a native Autodesk Revit dockable panel via IDockablePaneProvider — docks, floats, and resizes exactly like Revit's built-in panels.

• Docks to left, right, top, or bottom of the Revit canvas
• Floating mode — detach by dragging the panel header
• Panel state (position, size) is persisted by Revit across sessions
• Multiple palette panels can be opened simultaneously using different pane GUIDs

Each palette is organized into named tabs. Four formats control how button lists are built:

A persistent search bar filters buttons in real time. Matches against Label, Group, and Category simultaneously.

• Instant filtering — no submit, no delay
• Sort modes: Default, A→Z, Z→A, Favorites First, Recent First
• Favorite and recent order persist per palette across sessions

Click the star icon on any button to mark it as a favorite. A dedicated Favorites tab auto-appears, aggregating starred buttons from all tabs across tab boundaries.

• Favorites tab is auto-generated — no manual setup needed
• Favorites persist across Revit sessions in palette metadata
• Can be sorted and reordered via the Editor

Family buttons with multiple type variants expand a flyout sub-list on click. Two expansion modes are supported:

• One at a time: clicking a second button collapses the first
• Additive: multiple buttons can be expanded simultaneously
• Expand on mouseover can be toggled in Settings

Each button can display a custom PNG icon. Without one, the palette auto-generates an initials-based avatar from the button label — color-hashed for visual consistency.

• PNG icons at 32×32 px; SVG action glyphs for built-in actions
• Auto-avatar: initials from Label field, deterministic color hash
• Icon paths can be relative to the palette directory or absolute
• Revit family preview images can be extracted and used as icons automatically

Insert separator rows between button groups for visual hierarchy. Each separator supports an optional inline text label. Separators do not appear in search results.

The Reload button dispatches an ExternalEvent on the Revit API thread, re-fetching all dynamic tab content without requiring a Revit restart.

• Zero-restart reload for Doc Fetch, Template, and Folder tabs
• Keyboard shortcut: F5 while the Editor is focused
• Reload also re-evaluates Delegation rules

Auto-detects Revit's Light/Dark UI theme via a polling timer and applies the matching palette theme. Eight named themes ship out of the box.

On Revit 2025–2027, right-click any selected element and choose Add to Palette. Tool Palette extracts the family/type and creates a button in the target tab.

• Single element: single-add dialog with label and icon options
• Multi-element: bulk-add creates one button per unique family type
• Icon auto-extracted from Revit's family preview image when available

When enabled in Settings, SHIFT+right-clicking in the Revit canvas repeats the last palette button action without navigating back to the palette panel.

• Toggle: Settings → SHIFT+Right-Click Repeat Last Action
• Works for family placement and action buttons
• Last action clears on palette reload

A security sidecar controls which Windows users can open the Editor. Password hashing is supported. Admin and network role configurations allow fine-grained access control across team deployments.

• Editor password: optional, bcrypt-hashed — plain text never stored
• Admin users list bypasses the password entirely
• Security folder configurable separately from palette data
• Add-to-palette permissions controllable per deployment

The Editor is a modal WPF window running on the Revit API execution context — giving it direct access to the live document for real-time previewing and validation with no round-trips. Open it via BIMGrove → Open Editor.

It manages the entire palette data lifecycle: creating palettes and tabs, authoring buttons, configuring delegation rules, running the health checker, and managing security. All changes write directly to palette JSON files on save.

The left sidebar lists every palette registered in config.json. Each palette is independent with its own tabs, buttons, and meta settings.

• Create a new palette with ＋ — assigns a new JSON filename automatically
• Rename, duplicate, reorder via drag-and-drop, or delete from the sidebar
• Switching palettes animates the content area (slide transitions configurable)
• Delete removes from config.json; the JSON file is preserved for recovery

Tabs are managed in the tab strip at the top of the Editor. Create, rename, delete, and drag to reorder — order persists to the palette JSON on save.

• Create tab: click ＋, choose format (Custom / Doc Fetch / Template Fetch / Folder Fetch)
• Rename: double-click the tab label
• Reorder: drag the tab label in the tab strip
• Delete: right-click → Delete (confirmation if tab has buttons)

All button fields are editable inline in the button list. Rows can be multi-selected for bulk operations and dragged to reorder.

For fetch-type tabs, the Editor calls the live Revit API directly to preview exactly which buttons would be generated, including resolved family names, types, and categories.

• Preview triggered manually or automatically on tab focus
• Results cached per-tab to avoid redundant API calls
• Respects filter and exclusion settings defined on the tab

Scans all buttons for issues categorized by severity. Accessible from the Editor toolbar.

• Missing Icons: icon file not found on disk
• Missing Source Files: source_path .rfa cannot be resolved
• Invalid Action Parameters: required keys absent or malformed
• Unresolvable Families: family_name not found in document or template
• Orphaned Meta Entries: metadata references buttons that no longer exist
• Clicking a result navigates to the offending button

Scans a folder for .rfa files and auto-creates one button per family with auto-detected label, category, and source path.

• Recursive or top-level scan (configurable)
• Label auto-generated by stripping underscores and version suffixes
• Duplicate detection skips or updates existing buttons with the same family name
• Icons auto-extracted from Revit family preview images when available

Every field tracks its loaded state via CaptureLoadedState(). The IsDirty flag enables Save and Reset. Resetting reverts all fields to the last-saved snapshot.

• Dirty state tracked per-row and aggregated to palette level
• Save writes to JSON immediately — no publish step
• Closing with unsaved changes prompts for confirmation

When setting a button to action class, the picker dialog lists all available action IDs from built-in and loaded Action Packs. Selecting one auto-populates the parameters panel with all required and optional keys.

• Built-in BIMGrove Core Actions pack always available
• Third-party packs loaded from the configured Action Packs folder
• Parameters validated on save — missing required keys flagged by the Health Checker

Toggle to enable or disable family auto-loading on fetch tabs. When disabled, the Editor uses cached families until Reload (F5) is clicked — useful for large documents to avoid unnecessary API calls.

Tool Palette assignment called Delegation Rule is Tool Palette's project-aware routing engine. When enabled, it evaluates the active Revit document against a prioritized list of rules and loads the matching palette automatically — eliminating manual palette switching across disciplines and projects.

Particularly valuable in multi-discipline BIM teams where the same workstation serves Architectural, Structural, and MEP work, or where different client projects require different button sets.

A delegation rule pairs a palette name with a set of criteria and a user scope. Rules are evaluated top-to-bottom; the first match wins.

All criteria in a rule must match for the rule to fire (AND logic). Delegation schema version: 3 (current).

• Regex operator supports full .NET regular expression syntax
• Field matching is case-insensitive by default
• Criteria rows with enabled: false are skipped during evaluation
• Max palette slots (context menu): 32

The engine fires on document open and document switch. Rules evaluated in priority order (top = highest). When Delegation is ON, the Startup Palette setting is ignored — Delegation fully controls loading.

• Trigger: document open and document switch
• Multiple palettes can load simultaneously if multiple rules match different palettes
• When Delegation is OFF, the Startup Palette list (Column A) controls which palette opens on launch

Always add an All Documents / All Users rule as the last entry. This guarantees every user always lands on a valid palette when no project-specific rule matches.

• Set all_documents: true and all_users: true
• Assign it to a General or Studio default palette
• Position it last in the rule list (lowest priority)

Delegation Rule can be switched off to enable Startup Palette, which uses a fixed startup list. This allows you to specify one or more palettes to load when Revit starts, without using any delegation rules, and launch or relaunch palettes as needed.

• One or more palettes can be assigned to load on startup.
• Startup Palette can be set to <None> to prevent Revit from loading any Tool Palette on startup.
• Tool Palette can be closed during an active Revit session, and it will not automatically reopen when new files or views are opened. Use the Launcher button on the ribbon menu to bring Tool Palette back when needed.
• Ideal setting for individuals or teams who prefer to manually control Tool Palette loading without strict rules.

Open the Settings dialog from BIMGrove → Settings. It exposes global configuration for palette runtime, Editor behavior, security, licensing, and Action Packs. Settings are stored in ui_settings within config.json and can be overridden per user via UI profiles.

The root folder for all palette JSON files and config.json. Default: %AppData%\BIMGrove\PaletteProject. Can be redirected to a shared network path for team deployments.

• Browse to a new path in the Settings dialog
• Carry Existing Palettes to New Directory copies all JSON files on save
• Network path: all team members point to the same share — palette updates are instant

Controls which Autodesk users can open the Editor and change settings. Security config is stored separately from palette data to support network-managed policies. 

• Editor Password: optional; bcrypt-hashed — plain text never stored
• Admin Users: Autodesk ID usernames that bypass the editor password
• Security Folder: configurable path, defaults to a subfolder of the palette directory
• Changes take effect immediately on save — no restart required

Tool Palette ships as Personal (free) and Pro (paid). To activate Pro: open Settings under BIMGrove ribbon menu → Licensing tab and enter your email and activation code.