Core Concepts Importing Elements

Importing Elements

This article guides you through importing elements into Navigator. Importing elements allows you to use custom or experimental components that can be side-loaded into your Navigator environment, providing you a way to test new functionality before it's officially released or integrate custom-built elements into your workflows.

The Import Elements feature provides a simple way to add, manage, and organize side-loaded elements. You can import elements packaged as zip files, view all versions element, control versioning, and easily remove or replace beta versions as needed.

Overview

The Import Elements feature enables you to extend Navigator's capabilities by side-loading custom elements. This is particularly useful for:

  • Testing New Features → Preview upcoming elements before they're officially released
  • Custom Development → Import elements built with the Element SDK for your specific use cases
  • Rapid Prototyping → Quickly iterate on element designs without waiting for official releases
  • Team Collaboration → Share custom elements across your organization before formal distribution

Requirements

Before importing beta elements, ensure you have the following:

  • Navigator Version: Version 2.443.0 or later with beta import support enabled
  • Element Package: A valid zip file containing the element package

Importing Beta Elements

Drag and Drop

The quickest way to import an element is using the drag-and-drop interface.

  1. Open Navigator and navigate to any canvas.
  2. Open the Element Drawer and click the three dots ... on the top right within the Element Drawer

  3. Click Import Elements

  4. Locate the zip file(s) containing your element on your computer.
  5. Drag the zip file directly onto the Navigator window. A drop zone overlay will appear indicating where you can release the file.
  6. Release the file over the drop zone. Navigator will validate the package and display an import confirmation dialog.
  7. Review the element details in the confirmation dialog

  8. Click Import to complete the import, or Cancel to abort.

Beta vs Production

Beta tags will be added to your imported elements if the publish.json file in your elements package contains an unreleased value of true. If this value is false then the imported element will be treated as a production ready element. 

Beta Tags 

Once a beta version of the element is successfully imported you will see tags on the element within the Element Drawer stating beta available. 

Also within the Element Settings panel under the version dropdown, beta elements will have a beta tag next to version number. 

 

Replace a Beta Element with a Production Ready Element

Update an existing beta element with a newer production ready version:

  1. Make sure your publish.json file in your elements package contains an unreleased value of false
  2. Open Navigator and navigate to any canvas.
  3. Open the Element Drawer and click the three dots ... on the top right within the Element Drawer
  4. Click Import Elements
  5. Choose the new zip file containing the updated element.
  6. Click Import to complete the import
  7. A pop up modal should appear confirming the version update
  8. Click Replace to confirm the update.

After replacing a beta Element with a newer version you won't be able to install beta versions older than the previous installed version, however you can still continue to replace the beta Element with newer beta versions. 

Managing Beta Elements

Navigator provides a dedicated management modal for all your side-loaded beta elements. 

Accessing the Elements Version Manager

  1. Open Navigator and navigate to any canvas.
  2. Open the Element Drawer and click the three dots ... on the top right of the imported Element

  3. Click on Manage Versions

  4. You will see the option to remove beta versions

Troubleshooting

Import Fails with "Invalid Package" Error

This error occurs when the zip file doesn't meet the required package structure. Verify that:

  • The zip file contains an publish.json file at the root level

Element Shows "This version is already released" Warning

This warning appears when the version of the element already exists in Navigator.

  • Update the element version within the publish.json file
  • Reimport the element

"Please Drop a Zip" Warning

If you attempt to import a file that is not a zip file you will receive this warning. 

  • The Import Elements feature only accepts zip files. 

“One or more elements with the same version already exist in the import list. Please remove the duplicate elements.” Warning 

This warning appears when the version of the element already exists in Navigator.

  • Update the element version within the publish.json file or remove the duplicate elements from the import list. 

Related Articles