Skip to content

UI bundles

Start with the short introduction to bundles at Your first command.
See Bundle metadata for the bundle.yaml file and Bundle lib and bin for the lib/ and bin/ folders.
The other bundle types are on Command bundles and Advanced bundles.

UI bundles are designed to create easily sharable UI layouts for the Command Bundles

A UI bundle is a bundle that can contain command bundles and other UI bundles. There are some limitations depending which version of Revit is being used however pyRevit is usually smart about these differences.

All UI Bundles

The requirements and conventions below are shared among all UI bundles

requires:
    - bundle.yaml         # includes bundle metadata e.g. tooltip message

optional:
    - icon.png            # for Revit UI icons
    - icon.dark.png       # for Revit UI icons in Dark mode
    - lib/                # can include a lib/ directory that hosts modules required by the commands inside this bundle
    - bin/                # can include a bin/ directory that hosts binaries required by the commands inside this bundle

Bundle Layout Directives

UI bundles can provide directives on how the child bundles should be ordered in Revit UI. Since pyRevit 4.7, the primary method to provide these directives is to use the Bundle File. These directives are defined in the bundle file and are limited to UI bundles only.

See Bundle Layout for more information about layout directives

Example

# layout directives are listed in order under `layout` key
layout:
  - Logs
  - -----
  - Unit Tests
  - Bundle Tests
  - Misc Tests[title:Third-Party\nUnit Tests]
  - Debug Dialog Config

Tab UI Bundle

This bundle creates a Tab in the Ribbon with the bundle name. The rest of the required and optional components are identical to All UI Bundles

extension: .tab
can_contain: Only .panel bundles; all other bundles will be ignored

Panel UI Bundle

This bundle creates a Panel in a Ribbon Tab with the bundle name.

extension: .panel
can_contain: All other command and UI bundle types

Panel Background

You can set the background color for main, title, and slideout parts of a panel in the bundle metadata file. The colors are in CSS style and can be in ARGB or RGB format. Note that colors need to be wrapped in quotes since # is a comment character in YAML

# set background for all parts
background: '#ff0000'                   # or ARGB e.g. #ff0000ff

# or for individual parts
background:
  panel: '#ff0000'
  title: '#00ff00'
  slideout: '#0000ff'

Collapsing Panels By Default

If you have a lot of panels on your tab, you might want to set some of those tabs to be collapsed by default so they don't take space on the tab bar. Users can hover over the panels to see the tools. Set the option below in the Panel bundle file.

collapsed: true

This is how the panels would show up (collaped) and expand when user hovers over the panel.

Stack UI Bundle

extension: .stack
can_contain:
    - Pull-down UI bundle
    - Split-button UI bundle
    - Split-push-button UI bundle       # Revit 2018 and later
    - All command bundles

max_children: 3 bundles total (of any kind)

Pull-Down UI Bundle

This bundle creates a Pulldown Button in a Ribbon Panel or a Stack, with the bundle name and icon.

extension: .pulldown
can_contain: Other Command bundles

Split-Button UI Bundle

This bundle creates a Split Button button in a Ribbon Panel or a Stack, with the bundle name and icon.

extension: .splitbutton
can_contain: Other Command bundles

Split-Push-Button UI Bundle

This bundle creates a Split Push Button button (The sticky split button) in a panel or a stack, with the bundle name and icon.

extension: .splitpushbutton
can_contain: Other Command bundles

This bundle creates a stack of 2 or 3 buttons in a panel.