Customizing the Designer in SpreadJS, a JavaScript Spreadsheet Component

Quick Start Guide
Tutorial Concept Build and customize a JavaScript spreadsheet ribbon control using the SpreadJS Designer Ribbon Component and Vite. Configure ribbon tabs, context menus, dialogs, file menu panels, and more.
What You Will Need
Controls Referenced

SpreadJS a JavaScript Spreadsheet & the optional Designer Ribbon Component Add-On

Online Demo Explorer | Designer Component Sample App | Designer Component Documentation

The SpreadJS Designer Ribbon Component is the perfect solution for creating powerful spreadsheet user interfaces in JavaScript applications. As an add-on to the SpreadJS product, the Designer allows developers to quickly integrate a fully interactive spreadsheet editing experience into their web applications while giving end users the ability to customize, edit, and interact with workbooks directly inside the browser.

Out-of-the-box, the SpreadJS Designer provides a complete Excel-like interface with ribbon tabs, dialogs, context menus, file management tools, formatting options, and advanced spreadsheet functionality. However, many enterprise applications require additional customization beyond the default Designer experience. In some scenarios, developers may need to add their own ribbon tabs, create custom dialogs, extend context menus, modify existing Designer controls, or integrate application-specific workflows directly into the spreadsheet UI.

Fortunately, the Designer Ribbon Component is highly customizable and provides a flexible API that allows developers to extend nearly every part of the interface. Using the Designer customization APIs, you can create completely tailored spreadsheet experiences that match your application's requirements while still leveraging the full power of SpreadJS.

In this tutorial, you will build a custom JavaScript spreadsheet designer application using Vite and the latest MESCIUS SpreadJS packages. You will learn how to customize ribbon tabs and buttons, modify existing dropdown controls, create and register custom dialogs, enable and disable dialog controls dynamically, extend the context menu, customize the file menu interface, and add custom status bar items. By the end of this tutorial, you will have a modern, fully customizable spreadsheet Designer application built with SpreadJS and JavaScript.

Get Started Customizing a JS Spreadsheet Ribbon Component

Download a Finished Sample Application to Follow Along with the Tutorial.

Creating the Vite Application

Begin by creating a new Vite application. Open Visual Studio Code and launch a terminal window. Run the following command to create a new JavaScript application using Vite:

npm create vite@latest spreadjs-designer-custom-sample

When prompted, select the Vanilla framework and choose the JavaScript variant.

After the project has been created, navigate into the application directory and install the project dependencies:

cd spreadjs-designer-custom-sample
npm install

Next, install the SpreadJS Designer packages and related SpreadJS modules:

npm install @mescius/spread-sheets @mescius/spread-sheets-designer @mescius/spread-sheets-charts @mescius/spread-sheets-shapes @mescius/spread-sheets-print @mescius/spread-sheets-barcode @mescius/spread-sheets-pdf @mescius/spread-sheets-io @mescius/spread-sheets-pivot-addon @mescius/spread-sheets-tablesheet @mescius/spread-sheets-designer-resources-en

Initializing a JavaScript Designer Ribbon Component

After creating the project, replace the default Vite application files with the SpreadJS Designer setup. Update the index.html file so it contains a container element for the Designer:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>SpreadJS Designer Customization</title>
  </head>

  <body>
    <div id="designerHost"></div>

    <script type="module" src="/src/main.js"></script>
  </body>
</html>

Next, update the style.css file to ensure the Designer fills the browser window:

html,
body {
  margin: 0;
  padding: 0;
  width: 100%;
  height: 100%;
}

#designerHost {
  width: 100%;
  height: 100vh;
}

Now initialize the JS spreadsheet designer inside the main.js file using the Designer constructor. Developers can then programmatically access the spreadsheet workbook and active sheet.

import './style.css';
import * as GC from '@mescius/spread-sheets';
import '@mescius/spread-sheets/styles/gc.spread.sheets.excel2013white.css';
import '@mescius/spread-sheets-designer/styles/gc.spread.sheets.designer.min.css';
import '@mescius/spread-sheets-designer-resources-en';
import '@mescius/spread-sheets-designer';

const config = GC.Spread.Sheets.Designer.DefaultConfig;
const designer =
  new GC.Spread.Sheets.Designer.Designer(
    document.getElementById('designerHost'),
    config
  );

const spread = designer.getWorkbook();
const sheet = spread.getActiveSheet();
sheet.setValue(
  0,
  0,
  'SpreadJS Designer Customization Sample'
);

At this point, running the application will display the SpreadJS Designer inside the browser.

Build Familiar Spreadsheet Experiences in Enterprise Web Applications

Ready to try for Yourself? Download a Free Trial of SpreadJS and the Designer Ribbon Component Today!

Adding a Custom Ribbon Tab

One of the easiest ways to customize the Designer is by adding a new ribbon tab. The Designer configuration contains a ribbon array that can be modified dynamically.

Add the following code:

config.ribbon.push({
  id: 'contactUs',
  text: 'Contact Us',
  buttonGroups: [
    {
      label:
        'Contact sales at (+1) 412-681-4343 or us.sales@mescius.com',
      commandGroup: {}
    }
  ]
});

This code adds a new ribbon tab named Contact Us to the Designer interface.

Customize the JS Spreadsheet Ribbon Bars | Adding a New Custom Tab

Adding a Custom Ribbon Button

The Designer Ribbon Component also allows developers to add completely custom commands and buttons to the ribbon interface.

First, define a custom command using the Designer’s commadMap:

config.commandMap.Welcome = {
  title: 'Welcome',
  text: 'Welcome',
  iconClass: 'ribbon-button-welcome',
  bigButton: true,
  commandName: 'Welcome',
  execute: () => {
    alert('Welcome to the customized SpreadJS Designer.');
  }
};

Next, add the button to the Home tab:

config.ribbon[0].buttonGroups.unshift({
  label: 'Custom Buttons',
  commandGroup: {
    children: [
      {
        direction: 'vertical',
        commands: ['Welcome']
      }
    ]
  }
});

When the button is clicked, the custom command executes and displays an alert message.

Add a Custom Button to a JavaScript Spreadsheet Ribbon application

Editing an Existing Dropdown Control

Existing Designer controls can also be customized. In this example, the built-in font family dropdown is modified by removing Arial and adding a custom font option.

const fontFamilyCmd =
  GC.Spread.Sheets.Designer.getCommand('fontFamily');
if (fontFamilyCmd) {
  const originalList =
    fontFamilyCmd.dropdownList || [];
  const updatedList = originalList.filter(
    (item) => item.text !== 'Arial'
  );
  updatedList.unshift({
    value: 'Test',
    text: 'Test'
  });
  fontFamilyCmd.dropdownList = updatedList;
  config.commandMap.fontFamily =
    fontFamilyCmd;
}

This customization updates the Designer’s font family dropdown dynamically.

Modify an Existing Drop Down Control | JS Spreadsheet Designer Component

Creating a Custom Dialog

The SpreadJS Designer supports fully customizable dialog templates. Begin by creating a custom dialog template:

const insertSignatureTemplate = {
  title: 'Signature Dialog',
  content: [
    {
      type: 'FlexContainer',
      children: [
        {
          type: 'TextBlock',
          text: 'Insert Range'
        },
        {
          type: 'RangeSelect',
          title: 'Select Range'
        }
      ]
    }
  ]
};

Then register the template:

GC.Spread.Sheets.Designer.registerTemplate(
  'insertSignatureTemplate',
  insertSignatureTemplate
);

Add Custom Dialog to the JS Spreadsheet Designer Experience

Now create a command that opens the dialog:

config.commandMap.insertSignatureTemplate = {
  title: 'Insert Signature',
  text: 'Insert Signature',
  commandName: 'insertSignatureTemplate',
  execute: () => {
    GC.Spread.Sheets.Designer.showDialog(
      'insertSignatureTemplate'
    );
  }
};

Finally, add the command to the ribbon.

Creating a Custom Dialog in JS Spreadsheet Web Applications

Editing an Existing Dialog

Existing dialogs can also be modified. The following code updates the built-in Format Cells dialog title.

const formatCellsTemplate =
  GC.Spread.Sheets.Designer.getTemplate(
    'formatDialogTemplate'
  );
if (formatCellsTemplate) {
  formatCellsTemplate.title =
    'Custom Format Cells';
  GC.Spread.Sheets.Designer.registerTemplate(
    'formatDialogTemplate',
    formatCellsTemplate
  );
}

This allows developers to extend or replace portions of built-in Designer dialogs. Developers can see the list of the available TemplateNames here in the docs.

Editing a SpreadJS Designer Component Dialog | Developer Solution

Dynamically Enabling and Disabling Dialog Controls

Designer dialog controls support conditional enablement through the enableWhen property.

{
  type: 'RangeSelect',
  enableWhen: 'selectType=range'
}

Using conditional enablement allows developers to create more dynamic and interactive dialog experiences.

Dynamically Enabling and Disabling Dialog Controls Example

Adding a Custom Context Menu Item

The context menu can also be extended using the Designer configuration.

Add a new context menu using the commandMap:

config.commandMap.showAlert = {
  text: 'Show Alert',
  commandName: 'showAlert',
  visibleContext: 'ClickColHeader',
  execute: () => {
    alert(
      'You clicked the custom context menu item.'
    );
  }
};

Then register the menu item:

config.contextMenu.push('showAlert');

This adds a custom context menu option when right-clicking a column header.

Add a Custom Context Menu Item to a JavaScript Spreadsheet Designer Application

Customizing the File Menu

The Designer File menu can also be customized using template registration.

The following example adds a new Custom Actions section to the File Menu:

listContainer.items.push({
  text: 'Custom Actions',
  value: 'CustomItem'
});

Additional buttons and actions can then be registered and handled using the File menu command execution logic.

Customize the File Menu in a JavaScript Spreadsheet App

Adding a Custom Status Bar Item

The SpreadJS Status Bar API  allows developers to extend the status bar with custom items.

const statusBar =
  GC.Spread.Sheets.StatusBar.findControl(
    document.getElementsByClassName('gc-statusBar')
  );

const spanItem =
  new GC.Spread.Sheets.StatusBar.StatusItem(
    'spanItem',
    {
      menuContent: 'Show Contact',
      value:
        'Contact: us.sales@mescius.com'
    }
  );

statusBar.add(spanItem);

This customization displays custom contact information inside the Designer status bar.

Adding a Custom Status Bar Item to a JS Spreadsheet Designer Ribbon

Hiding UI Elements with CSS

In some cases, it may be useful to hide built-in Designer UI components using CSS.

div[buttontype="diagonalUpLine"] {
  display: none !important;
}
div[buttontype="diagonalDownLine"] {
  display: none !important;
}

This CSS removes the diagonal border buttons from the Format Cells dialog.

Hiding UI Elements with CSS Example

Conclusion

The SpreadJS Designer Ribbon Component provides a powerful and highly customizable spreadsheet UI that can be fully integrated into modern JavaScript applications. By combining the flexibility of the Designer APIs with the rich spreadsheet functionality available in SpreadJS, developers can build customized spreadsheet experiences tailored to their application's specific business requirements.

These examples represent only a small portion of what can be customized within the SpreadJS Designer Ribbon Component. The Designer API provides extensive flexibility for creating enterprise-grade spreadsheet interfaces with fully tailored user experiences.

Ready to Get Started? Download a free trial of SpreadJS today!

Review the documentation to see some of the many available features, and check out our online demos to see the features in action and interact with the sample code.

Tags:

Related Blogs

Try Our JavaScript Spreadsheet Components

SpreadJS Resources

Learn More About SpreadJS
Release Information
Pricing and Licensing
Product Documentation

Kristina Ismail

Product Specialist
comments powered by Disqus