Search Docs
Loading...
Skip to content

Navigation Bar

The navigation bar is the horizontal toolbar at the top of the editor containing buttons for back navigation, undo/redo, zoom controls, and action buttons. This guide covers navigation bar-specific features like the actions dropdown, back/close buttons, and callback integration.

Navigation Bar Hero

10 mins
estimated time
Download
StackBlitz
GitHub

Actions that affect browser navigation (e.g., going back or closing the editor), have global effects on the scene (e.g., undo/redo and zoom), or process the scene in some way (e.g., saving and exporting) belong in the navigation bar.

For general component manipulation (reordering, inserting, removing), see the Component Order API Reference. For a complete list of navigation bar component IDs, see the Component Reference.

This guide covers:

  • Showing or hiding the navigation bar and sub-components
  • Configuring the actions dropdown with grouped actions
  • Adding back and close buttons with handlers
  • Customizing button styles and variants
  • Integrating with the Callbacks API

Show or Hide the Navigation Bar#

Use the Feature API to control navigation bar visibility. The Feature API hides features globally across the entire editor.

// Hide undo/redo using the Feature API
cesdk.feature.disable('ly.img.navigation.undoRedo');

The following feature keys control navigation bar sub-components:

Feature KeyControls
ly.img.navigation.barEntire navigation bar
ly.img.navigation.undoRedoUndo/redo buttons
ly.img.navigation.zoomZoom controls
ly.img.navigation.previewPreview toggle

For more visibility control options, see Show/Hide Components.

Add Back and Close Buttons#

Back and close buttons only appear when explicitly inserted with an onClick handler. Use insertOrderComponent with explicit positioning to place them at the start and end of the navigation bar.

Add a back button at the start using position: 'start':

// Insert a back button at the start of the navigation bar
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.navigation.bar', position: 'start' },
  {
    id: 'ly.img.back.navigationBar',
    onClick: () => {
      console.log('Back button clicked');
      window.history.back();
    }
  }
);

Add a close button at the end using position: 'end':

// Insert a close button at the end of the navigation bar
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.navigation.bar', position: 'end' },
  {
    id: 'ly.img.close.navigationBar',
    onClick: () => {
      console.log('Close button clicked');
    }
  }
);

Both buttons require an onClick handler. Without one, the button will not render.

Configure the Actions Dropdown#

The ly.img.actions.navigationBar component groups multiple actions into a dropdown menu. The first child appears as a prominent button, while additional children appear in the overflow dropdown.

The actions dropdown is not in the navigation bar by default. Use insertOrderComponent to add it with your own actions:

// Insert the actions dropdown with export options
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.navigation.bar', before: 'ly.img.close.navigationBar' },
  {
    id: 'ly.img.actions.navigationBar',
    children: [
      {
        id: 'ly.img.saveScene.navigationBar',
        onClick: async () => {
          const scene = await cesdk.engine.scene.saveToString();
          console.log('Scene saved:', scene.length, 'characters');
          cesdk.ui.showNotification({
            message: 'Scene saved to console',
            type: 'success',
            duration: 'short'
          });
        }
      },
      {
        id: 'ly.img.exportImage.navigationBar',
        onClick: async () => {
          const { blobs } = await cesdk.utils.export({
            mimeType: 'image/png'
          });
          cesdk.utils.downloadFile(blobs[0], 'image/png');
        }
      },
      {
        id: 'ly.img.action.navigationBar',
        key: 'print',
        label: 'Print',
        icon: '@imgly/Print',
        onClick: () => {
          window.print();
        }
      }
    ]
  }
);

Children can be built-in action buttons (referenced by ID like ly.img.saveScene.navigationBar) or custom actions with a unique key. Each child needs an onClick handler to define its behavior.

Button Styles and Variants#

Custom action buttons support different visual styles through the variant and color properties.

// Add buttons demonstrating different style variants
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.navigation.bar', before: 'ly.img.close.navigationBar' },
  [
    // Regular variant (default) - standard button appearance
    {
      id: 'ly.img.action.navigationBar',
      key: 'preview',
      label: 'Preview',
      icon: '@imgly/EyeOpen',
      variant: 'regular' as const,
      onClick: () => {
        cesdk.ui.showNotification({
          message: 'Opening preview...',
          type: 'info',
          duration: 'short'
        });
      }
    },
    // Plain variant - subtle/borderless appearance
    {
      id: 'ly.img.action.navigationBar',
      key: 'reset',
      label: 'Reset',
      icon: '@imgly/Reset',
      variant: 'plain' as const,
      color: 'danger' as const,
      onClick: () => {
        cesdk.ui.showNotification({
          message: 'Reset would clear all changes',
          type: 'warning',
          duration: 'short'
        });
      }
    }
  ]
);

The available properties for action buttons are:

PropertyTypeDescription
keystringUnique identifier (required for custom actions)
labelstringText label or i18n key
iconstringIcon from the Essentials set or custom icon via addIconSet
variant'regular' | 'plain'Button style (default: 'regular')
color'accent' | 'danger'Button color for emphasis
onClick() => void | Promise<void>Click handler (shows spinner if returning a promise)
isDisabledbooleanDisable the button
isLoadingbooleanShow loading state

Integration with Callbacks API#

Action buttons can trigger registered callbacks. Register a callback using cesdk.actions.register(), then reference it by inserting a built-in action button that maps to that callback name.

// Register a custom callback
cesdk.actions.register('saveScene', async () => {
  const scene = await cesdk.engine.scene.saveToString();
  console.log('Custom save callback:', scene.length, 'characters');
  cesdk.ui.showNotification({
    message: 'Scene saved via custom callback',
    type: 'success',
    duration: 'short'
  });
});

When you insert a built-in action button by its ID (e.g., ly.img.saveScene.navigationBar), it will call the registered callback with the matching name. You can also override the default behavior by providing a custom onClick handler directly on the button.

Default Callback Behaviors#

When using built-in action button IDs without registering a custom callback, the default behavior is triggered:

Component IDCallbackDefault Behavior
ly.img.saveScene.navigationBarsaveSceneDownloads .scene file
ly.img.importScene.navigationBarimportSceneOpens file picker for .scene
ly.img.exportImage.navigationBarexportDesignExports and downloads image
ly.img.exportPDF.navigationBarexportDesignExports and downloads PDF
ly.img.exportVideo.navigationBarexportDesignExports and downloads video
ly.img.shareScene.navigationBarshareSceneRequires callback registration

Standalone Action Buttons#

In addition to the actions dropdown, you can insert standalone action buttons directly into the navigation bar. This is useful for frequently-used actions that should always be visible.

// Add a standalone action button with accent styling
cesdk.ui.insertOrderComponent(
  { in: 'ly.img.navigation.bar', before: 'ly.img.close.navigationBar' },
  {
    id: 'ly.img.action.navigationBar',
    key: 'share',
    label: 'Share',
    icon: '@imgly/Share',
    color: 'accent',
    onClick: async () => {
      cesdk.ui.showNotification({
        message: 'Share dialog would open here',
        type: 'info',
        duration: 'short'
      });
    }
  }
);

Standalone buttons appear alongside the other navigation bar components. Use the before and after position options to control placement relative to other components.

Troubleshooting#

  • Back/close button not appearing — These require an explicit onClick handler when inserted.
  • Actions not showing children — Ensure children array contains valid action components with unique key values.
  • Sub-component still visible after disable — Verify exact Feature API key spelling.

Next Steps#