Getting started with JavaScript Ribbon control

22 Jul 202624 minutes to read

This section explains the steps required to create a simple Essential^® JS 2 Ribbon and demonstrates the basic usage of the Ribbon control in a JavaScript application.

Prerequisites

Before getting started, ensure the following requirements are met:

Requirement	Notes
Modern web browser	Chrome, Firefox, Edge, or Safari — latest version recommended
Code editor	Visual Studio Code is recommended
Local HTTP server	Required to serve the application. Opening HTML files directly via file:// may block script loading in some browsers. VS Code Live Server extension is recommended
Syncfusion® license key	Required from version 16.2.0.17 onwards. Refer to the Registering a license key section

Dependencies

The following list of dependencies are required to use the Ribbon control in your application.

|-- @syncfusion/ej2-ribbon
    |-- @syncfusion/ej2-base
    |-- @syncfusion/ej2-data
    |-- @syncfusion/ej2-buttons
    |-- @syncfusion/ej2-popups
    |-- @syncfusion/ej2-splitbuttons
    |-- @syncfusion/ej2-inputs
    |-- @syncfusion/ej2-lists
    |-- @syncfusion/ej2-dropdowns
    |-- @syncfusion/ej2-navigations

For npm-based projects, install the packages using: npm install @syncfusion/ej2-ribbon --save

Control Initialization

The Essential^® JS 2 JavaScript controls can be initialized by using either of the following ways.

• Using local script and style references in a HTML page.
• Using CDN link for script and style reference.

Using local script and style references in a HTML page

Step 1: Create an app folder quickstart for getting started.

Step 2: You can get the global scripts and styles from the Essential Studio^® JavaScript (Essential^® JS 2) build installed location.

Syntax:

Dependency Script: **(installed location)**\Syncfusion\Essential Studio\JavaScript - EJ2\{RELEASE_VERSION}\Web (Essential JS 2)\JavaScript\{DEPENDENCY_PACKAGE_NAME}\dist\global\{DEPENDENCY_PACKAGE_NAME}.min.js

Control Script: **(installed location)**\Syncfusion\Essential Studio\JavaScript - EJ2\{RELEASE_VERSION}\Web (Essential JS 2)\JavaScript\{PACKAGE_NAME}\dist\global\{PACKAGE_NAME}.min.js

Dependency Styles: **(installed location)**\Syncfusion\Essential Studio\JavaScript - EJ2\{RELEASE_VERSION}\Web (Essential JS 2)\JavaScript\{DEPENDENCY_PACKAGE_NAME}\styles\bootstrap5.3.css

Control Styles: **(installed location)**\Syncfusion\Essential Studio\JavaScript - EJ2\{RELEASE_VERSION}\Web (Essential JS 2)\JavaScript\{PACKAGE_NAME}\styles\bootstrap5.3.css

Example:

Dependency Script: C:\Program Files (x86)\Syncfusion\Essential Studio\JavaScript - EJ2\21.1.35\Web (Essential JS 2)\JavaScript\ej2-base\dist\global\ej2-base.min.js

Control Script: C:\Program Files (x86)\Syncfusion\Essential Studio\JavaScript - EJ2\21.1.35\Web (Essential JS 2)\JavaScript\ej2-navigations\dist\global\ej2-navigations.min.js

Dependency Styles: C:\Program Files (x86)\Syncfusion\Essential Studio\JavaScript - EJ2\21.1.35\Web (Essential JS 2)\JavaScript\ej2-base\styles\bootstrap5.3.css

Control Styles: C:\Program Files (x86)\Syncfusion\Essential Studio\JavaScript - EJ2\21.1.35\Web (Essential JS 2)\JavaScript\ej2-navigations\styles\bootstrap5.3.css

The below located script and style file contains all Syncfusion^® JavaScript (ES5) UI control resources in a single file.

Scripts: **(installed location)**\Syncfusion\Essential Studio\JavaScript - EJ2\{RELEASE_VERSION}\Web (Essential JS 2)\JavaScript\ej2\dist\ej2.min.js

Styles: **(installed location)**\Syncfusion\Essential Studio\JavaScript - EJ2\{RELEASE_VERSION}\Web (Essential JS 2)\JavaScript\ej2\bootstrap5.3.css

The Custom Resource Generator (CRG) is an online web tool, which can be used to generate the custom script and styles for a set of specific controls. This web tool is useful to combine the required control scripts and styles in a single file.

Step 3: Create a folder ~/quickstart/resources and copy/paste the global scripts and styles from the above installed location to quickstart/resources/package corresponding package location.

Step 4: Create a HTML page (index.html) in ~/quickstart/index.html location and add the Essential^® JS 2 script and style references.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Essential JS 2 - Ribbon</title>
    <!-- Essential JS 2 Ribbon's dependent material theme -->
    <link href="resources/base/bootstrap5.3.css" rel="stylesheet" type="text/css" />
    <link href="resources/buttons/bootstrap5.3.css" rel="stylesheet" type="text/css" />
    <link href="resources/popups/bootstrap5.3.css" rel="stylesheet" type="text/css" />
    <link href="resources/splitbuttons/bootstrap5.3.css" rel="stylesheet" type="text/css" />
    <link href="resources/inputs/bootstrap5.3.css" rel="stylesheet" type="text/css" />
    <link href="resources/lists/bootstrap5.3.css" rel="stylesheet" type="text/css" />
    <link href="resources/dropdowns/bootstrap5.3.css" rel="stylesheet" type="text/css" />
    <link href="resources/navigations/bootstrap5.3.css" rel="stylesheet" type="text/css" />
    <!-- Essential JS 2 Ribbon's control material theme -->
    <link href="resources/ribbon/bootstrap5.3.css" rel="stylesheet" type="text/css" />

    <!-- Essential JS 2 Ribbon's dependent global script -->
    <script src="resources/base/ej2-base.min.js" type="text/javascript"></script>
    <script src="resources/data/ej2-data.min.js" type="text/javascript"></script>
    <script src="resources/buttons/ej2-buttons.min.js" type="text/javascript"></script>
    <script src="resources/popups/ej2-popups.min.js" type="text/javascript"></script>
    <script src="resources/splitbuttons/ej2-splitbuttons.min.js" type="text/javascript"></script>
    <script src="resources/inputs/ej2-inputs.min.js" type="text/javascript"></script>
    <script src="resources/lists/ej2-lists.min.js" type="text/javascript"></script>
    <script src="resources/dropdowns/ej2-dropdowns.min.js" type="text/javascript"></script>
    <script src="resources/navigations/ej2-navigations.min.js" type="text/javascript"></script>
    <!-- Essential JS 2 Ribbon's control global script -->
    <script src="resources/ribbon/ej2-ribbon.min.js" type="text/javascript"></script>
  </head>
  <body></body>
</html>

Step 5: Now, add the Ribbon element and initiate the Syncfusion^® JavaScript Ribbon control in the index.html by using the following code snippet.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">

  <body>
    <!--element which is going to render-->
    <div id="ribbon"></div>

    <script>
      var ribbon = new ej.ribbon.Ribbon({});
      ribbon.appendTo("#ribbon");
    </script>
  </body>
</html>

Step 6: In ribbon, the options are arranged in tabs for easy access. Now, add the ribbon tabs using the tabs property of ribbon like below.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">

  <body>
    <!--element which is going to render-->
    <div id="ribbon"></div>

    <script>
      var ribbon = new ej.ribbon.Ribbon({
        tabs: [
          { header: "Home" }
        ]
      });
      ribbon.appendTo("#ribbon");
    </script>
  </body>
</html>

Step 7: Now, define ribbon groups under each tab, using the groups property of ribbon tab like below. The orientation property of ribbon group defines whether the collection of items will be rendered column-wise or row-wise.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">

  <body>
    <!--element which is going to render-->
    <div id="ribbon"></div>

    <script>
      var ribbon = new ej.ribbon.Ribbon({
        tabs: [{
            header: "Home",
            groups: [
                { header: "Clipboard", orientation: "Row"}
            ]
        }]
      });
      ribbon.appendTo("#ribbon");
    </script>
  </body>
</html>

Step 8: Now, add the ribbon collections using the collections property of ribbon group to define each ribbon collection that contains one or more items. Define each ribbon item, using the items property of ribbon collection and use the type property of ribbon item to specify the type of control to be rendered, like a button, a drop-down button, a combo box, and more.

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">

  <body>
    <!--element which is going to render-->
    <div id="ribbon"></div>

    <script>
      var ribbon = new ej.ribbon.Ribbon({
        tabs: [{
            header: "Home",
            groups: [{
                header: "Clipboard",
                orientation: "Row",
                collections: [
                    {
                        id : "paste-collection",
                        items: [{
                            type: "SplitButton",
                            allowedSizes: ej.ribbon.RibbonItemSize.Large,
                            splitButtonSettings: {
                                iconCss: "e-icons e-paste",
                                items: [{ text: "Keep Source Format" }, { text: "Merge format" }, { text: "Keep text only" }],
                                content: "Paste"
                            }
                        }]
                    },
                    {
                        id : "cutcopy-collection",
                        items: [{
                            type: "Button",
                            buttonSettings: {
                                content: "Cut",
                                iconCss: "e-icons e-cut"
                            }
                        }, {
                            type: "Button",
                            buttonSettings: {
                                content: "Copy",
                                iconCss: "e-icons e-copy"
                            }
                        }]
                    }]
            }]
        }]
      });
      ribbon.appendTo("#ribbon");
    </script>
  </body>
</html>

Step 9: Now, run the index.html in web browser, it will render the Syncfusion^® JavaScript Ribbon control.

Using CDN link for script and style reference

Step 1: Create an app folder quickstart for getting started.

Step 2: The Essential^® JS 2 control’s global scripts and styles are already hosted in the below CDN link formats.

Syntax:

Dependency Script: https://cdn.syncfusion.com/ej2/{DEPENDENCY_PACKAGE_NAME}/dist/global/{PACKAGE_NAME}.min.js

Control Script: https://cdn.syncfusion.com/ej2/{PACKAGE_NAME}/dist/global/{PACKAGE_NAME}.min.js

Dependency Styles: https://cdn.syncfusion.com/ej2/{DEPENDENCY_PACKAGE_NAME}/styles/bootstrap5.3.css

Control Styles: https://cdn.syncfusion.com/ej2/{PACKAGE_NAME}/styles/bootstrap5.3.css

Example:

Script: https://cdn.syncfusion.com/ej2/ej2-navigations/dist/global/ej2-navigations.min.js

Styles: https://cdn.syncfusion.com/ej2/ej2-navigations/styles/bootstrap5.3.css

Step 3: Create a HTML page (index.html) in ~/quickstart/index.html location and add the CDN link references. Now, add the Ribbon element and initiate the Syncfusion^® JavaScript Ribbon control in the index.html by using following code.

index.html

<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
    <head>                
        <title>Essential JS 2 - Ribbon</title>
        <!-- Essential JS 2 Ribbon's dependent material theme -->
        <link href="https://cdn.syncfusion.com/ej2/34.1.29/ej2-base/styles/tailwind3.css" rel="stylesheet" type="text/css" />
        <link href="https://cdn.syncfusion.com/ej2/34.1.29/ej2-buttons/styles/tailwind3.css" rel="stylesheet" type="text/css" />
        <link href="https://cdn.syncfusion.com/ej2/34.1.29/ej2-popups/styles/tailwind3.css" rel="stylesheet" type="text/css" />
        <link href="https://cdn.syncfusion.com/ej2/34.1.29/ej2-splitbuttons/styles/tailwind3.css" rel="stylesheet" type="text/css" />
        <link href="https://cdn.syncfusion.com/ej2/34.1.29/ej2-inputs/styles/tailwind3.css" rel="stylesheet" type="text/css" />
        <link href="https://cdn.syncfusion.com/ej2/34.1.29/ej2-lists/styles/tailwind3.css" rel="stylesheet" type="text/css" />
        <link href="https://cdn.syncfusion.com/ej2/34.1.29/ej2-dropdowns/styles/tailwind3.css" rel="stylesheet" type="text/css" />
        <link href="https://cdn.syncfusion.com/ej2/34.1.29/ej2-navigations/styles/tailwind3.css" rel="stylesheet" type="text/css" />
        <!-- Essential JS 2 Ribbon's material theme -->
        <link href="https://cdn.syncfusion.com/ej2/34.1.29/ej2-ribbon/styles/tailwind3.css" rel="stylesheet" type="text/css" />

        <!-- Essential JS 2 Ribbon's dependent scripts -->
        <script src="https://cdn.syncfusion.com/ej2/34.1.29/ej2-base/dist/global/ej2-base.min.js" type="text/javascript"></script>
        <script src="https://cdn.syncfusion.com/ej2/34.1.29/ej2-data/dist/global/ej2-data.min.js" type="text/javascript"></script>
        <script src="https://cdn.syncfusion.com/ej2/34.1.29/ej2-buttons/dist/global/ej2-buttons.min.js" type="text/javascript"></script>
        <script src="https://cdn.syncfusion.com/ej2/34.1.29/ej2-popups/dist/global/ej2-popups.min.js" type="text/javascript"></script>
        <script src="https://cdn.syncfusion.com/ej2/34.1.29/ej2-splitbuttons/dist/global/ej2-splitbuttons.min.js" type="text/javascript"></script>
        <script src="https://cdn.syncfusion.com/ej2/34.1.29/ej2-inputs/dist/global/ej2-inputs.min.js" type="text/javascript"></script>
        <script src="https://cdn.syncfusion.com/ej2/34.1.29/ej2-lists/dist/global/ej2-lists.min.js" type="text/javascript"></script>
        <script src="https://cdn.syncfusion.com/ej2/34.1.29/ej2-dropdowns/dist/global/ej2-dropdowns.min.js" type="text/javascript"></script>
        <script src="https://cdn.syncfusion.com/ej2/34.1.29/ej2-navigations/dist/global/ej2-navigations.min.js" type="text/javascript"></script>

        <!-- Essential JS 2 Ribbon's global script -->
        <script src="https://cdn.syncfusion.com/ej2/34.1.29/ej2-ribbon/dist/global/ej2-ribbon.min.js" type="text/javascript"></script>
        <style>
            .ribbonTemplate {
                display: flex;
                align-items: center;
                justify-content: center;
                cursor: pointer;
            }

            .ribbonTemplate.Large {
                flex-direction: column;
            }

            .ribbonTemplate.Large .e-icons {
                font-size: 35px;
            }

            .ribbonTemplate.Medium .e-icons,
            .ribbonTemplate.Small .e-icons{
                font-size: 20px;
                margin: 15px 5px;
            }

            .ribbonTemplate.Small .text {
                display:none;
            }

            .font-group .e-ribbon-group-content {
                justify-content: center;
            }
        </style>
    </head>
  <body>
<!--element which is going to render-->
<div id="ribbon"></div>

<script>
var fontSize = ["8", "9", "10", "11", "12", "14", "16", "18", "20", "22", "24", "26", "28", "36", "48", "72", "96"];
var fontStyle = ["Algerian", "Arial", "Calibri", "Cambria", "Cambria Math", "Courier New", "Candara", "Georgia", "Impact", "Segoe Print", "Segoe Script", "Segoe UI", "Symbol", "Times New Roman", "Verdana", "Windings"
];
var tabs = [{
    header: "Home",
    groups: [{
        header: "Clipboard",
        showLauncherIcon: true,
        groupIconCss: "e-icons e-paste",
        collections: [{
            items: [{
                type: "SplitButton",
                simplifiedMode: "Group",
                allowedSizes: ej.ribbon.RibbonItemSize.Large,
                splitButtonSettings: {
                    iconCss: "e-icons e-paste",
                    items: [{ text: "Keep Source Format" }, { text: "Merge format" }, { text: "Keep text only" }],
                    content: "Paste"
                }
            }]
        }, {
            items: [{
                type: "Button",
                buttonSettings: {
                    content: "Cut",
                    iconCss: "e-icons e-cut"
                }
            }, {
                type: "Button",
                buttonSettings: {
                    content: "Copy",
                    iconCss: "e-icons e-copy"
                }
            }, {
                type: "Button",
                buttonSettings: {
                    content: "Format Painter",
                    iconCss: "e-icons e-format-painter"
                }
            }]
        },]
    }, {
        header: "Font",
        isCollapsible: false,
        enableGroupOverflow: true,
        orientation: "Row",
        groupIconCss: "e-icons e-bold",
        cssClass: "font-group",
        collections: [{
            items: [{
                type: "ComboBox",
                simplifiedMode:"Group",
                comboBoxSettings: {
                    dataSource: fontStyle,
                    index: 3,
                    allowFiltering: true,
                    width: "150px"
                }
            }, {
                type: "ComboBox",
                simplifiedMode: "Group",
                comboBoxSettings: {
                    dataSource: fontSize,
                    allowFiltering: true,
                    index: 3,
                    width: "65px"
                }
            }]
        }, {
            items: [{
                    type: "ColorPicker",
                    displayOptions: ej.ribbon.DisplayMode.Simplified,
                    allowedSizes: ej.ribbon.RibbonItemSize.Small,
                    colorPickerSettings: {
                        value: "#123456",
                    }
                },{
                    type: "Button",
                    allowedSizes: ej.ribbon.RibbonItemSize.Small,
                    buttonSettings: {
                        iconCss: "e-icons e-bold",
                        content: "Bold"
                    }
                }, {
                    type: "Button",
                    allowedSizes: ej.ribbon.RibbonItemSize.Small,
                    buttonSettings: {
                        iconCss: "e-icons e-italic",
                        content: "Italic"
                    }
                }, {
                    type: "Button",
                    allowedSizes: ej.ribbon.RibbonItemSize.Small,
                    buttonSettings: {
                        iconCss: "e-icons e-underline",
                        content: "Underline"
                    }
                },{
                    allowedSizes: ej.ribbon.RibbonItemSize.Small,
                    type: "Button",
                    buttonSettings: {
                        iconCss: "e-icons e-strikethrough",
                        content: "Strikethrough"
                    }
                }, {
                    allowedSizes:ej.ribbon.RibbonItemSize.Small,
                    type: "Button",
                    buttonSettings: {
                        iconCss: "e-icons e-change-case",
                        content: "Strikethrough"
                    }
                }
            ]
        }]
    }, {
        header: "Editor",
        isCollapsible: false,
        collections: [{
            items: [{
                type: "Button",
                allowedSizes: ej.ribbon.RibbonItemSize.Large,
                buttonSettings: {
                    content: "Editor",
                    iconCss:"e-icons e-edit"
                }
            }]
        }]
    }]
}, {
    header: "Insert",
    groups: [{
        header: "Tables",
        isCollapsible: false,
        collections: [{
            items: [{
                simplifiedMode:"Group",
                type: "SplitButton",
                allowedSizes: ej.ribbon.RibbonItemSize.Large,
                splitButtonSettings: {
                    iconCss: "e-icons e-table",
                    content: "Table",
                    items: [
                        { text: "Insert Table" }, { text: "Draw Table" },
                        { text: "Convert Table" }, { text: "Excel SpreadSheet" }
                    ]
                }
            }]
        }]
    }, {
        header: "Illustrations",
        orientation: "Row",
        enableGroupOverflow: true,
        groupIconCss: "e-icons e-image",
        collections: [{
            items: [{
                type: "Button",
                buttonSettings: {
                    content: "Chart",
                    iconCss:"e-icons e-chart"
                }
            }]
        }]
    }, {
        header: "Media",
        isCollapsible: false,
        collections: [{
            items: [{
                type: "Template",
                itemTemplate: "#itemTemplate"
            }]
        }]
    }]
}, {
    header: "View",
    groups: [{
        header: "Views",
        groupIconCss: "e-icons e-print",
        orientation: "Row",
        collections: [{
            items: [{
                type: "Button",
                buttonSettings: {
                    content: "Print Layout",
                    iconCss: "e-print e-icons"
                }
            }, {
                type: "Button",
                buttonSettings: {
                    iconCss: "e-icons e-web-layout",
                    content: "Web Layout"
                }
            }]
        }]
    }, {
        header: "Show",
        isCollapsible: false,
        collections: [{
            items: [{
                type: "CheckBox",
                checkBoxSettings: {
                    label: "Ruler",
                    checked: false
                }
            }, {
                type: "CheckBox",
                checkBoxSettings: {
                    checked: false,
                    label: "Gridlines"
                }
            }, {
                type: "CheckBox",
                checkBoxSettings: {
                    label: "Navigation Pane",
                    checked: true
                }
            }]
        }]
    }]
}];
var menuItems = [
    { text: "New", iconCss: "e-icons e-file-new", id: "new" },
    { text: "Open", iconCss: "e-icons e-folder-open", id: "Open" },
    { text: "Rename", iconCss: "e-icons e-rename", id: "rename" },
    { text: "Save as", iconCss: "e-icons e-save", id: "save" }
];
var ribbon = new ej.ribbon.Ribbon({
    tabs: tabs,
    fileMenu: {
        menuItems: menuItems,
        visible: true
    }
});
ribbon.appendTo("#ribbon");
</script>
<script type="text/x-jsrender" id="itemTemplate">
    <span class="ribbonTemplate ${activeSize}">
        <span class="e-icons e-video"></span>
        <span class="text">Video</span>
      </span>
</script>
  </body>
</html>

Registering a license key

Syncfusion^® Essential^® JS 2 controls require a valid license key from version 16.2.0.17 onwards. Without a license key, a license validation message will appear in the browser console.

Step 1: Obtain your license key from the Syncfusion License Portal or from the licensing FAQ page.

Step 2: Register the license key in your index.js file before initializing any Syncfusion^® control.

// Register Syncfusion license key
ej.base.registerLicense('YOUR_LICENSE_KEY_HERE');

Replace 'YOUR_LICENSE_KEY_HERE' with the actual license key obtained from your Syncfusion account. For more information, refer to the Syncfusion Licensing documentation.

Step 4: Now, run the index.html in web browser, it will render the Syncfusion^® JavaScript Ribbon control.

Troubleshooting

Ribbon renders blank / does not load

• Verify that the container element exists and has a valid ID.
• Open the browser developer console (F12) and check for JavaScript errors.
• Ensure all CDN script tags are loading successfully (check the Network tab for 4xx/5xx errors).

License validation warning in the console

• Register your license key before instantiating any Syncfusion^® control.

Scripts blocked when opening via file://

• Serve the application through a local HTTP server.

CDN resources fail to load

• Check your internet connection.
• Confirm the version number in the CDN URLs matches a valid published release. See the Syncfusion CDN page for available versions.