Syncfusion React Ribbon

Syncfusion React Ribbon

Component Overview

The Syncfusion React Ribbon component is a professional, feature-rich toolbar designed for creating command-centric user interfaces inspired by Microsoft Office. It provides an intuitive hierarchical structure that organizes related commands into visually distinct tabs and groups, enabling users to quickly discover and execute actions.

Key Capabilities

• Tabbed Ribbon Interface: Organize commands into logical tabs for easy navigation and grouping
• Dual Layout Modes: Support for Classic (multi-row) and Simplified (single-row) layouts with dynamic switching
• Multiple Item Types: Buttons, checkboxes, dropdowns, split buttons, combo boxes, color pickers, group buttons, galleries, and custom templates
• Responsive Resizing: Automatically adjust item sizes (Large, Medium, Small) based on available space
• File Menu & Backstage View: Complete file menu with traditional File menu or modern backstage interface
• Contextual Tabs: Show/hide tabs dynamically based on user selection or application state
• Gallery Support: Visual selection galleries with grouping, filtering, and custom item templates
• KeyTips & Keyboard Navigation: Accessibility-first keyboard navigation with KeyTip support
• Group Overflow Management: Control group priority and dedicated overflow popups for better space utilization
• Rich Customization: Custom CSS classes, item templates, icons, and layout control
• Comprehensive Event Handling: itemClick, tabSelected, fileMenuSelect, and more for precise control
• Multi-Theme Support: Material, Bootstrap, Fluent, and Tailwind CSS themes with dark mode
• RTL & Accessibility: Full right-to-left language support and WCAG compliance with ARIA attributes
• Help Pane Integration: Built-in help pane for contextual assistance and documentation

Hierarchical Structure:

• Ribbon (root container) - Main toolbar component
• Tabs (e.g., Home, Insert, View, Design) - Logical command groupings
• Groups (e.g., Clipboard, Font, Styles) - Related command categories
• Collections (logical item containers) - Item arrangement helpers
• Items (buttons, dropdowns, galleries, color pickers, etc.) - Individual commands and controls

Documentation

Getting Started

📄 Read: references/getting-started.md

• Installation and package setup
• Basic ribbon component implementation
• CSS imports and themes
• First working example
• TypeScript configuration

Ribbon Structure

📄 Read: references/ribbon-structure.md

• Tabs creation and configuration
• Groups organization and hierarchy
• Collections and item containers
• Tab header properties
• Group headers and icons
• Item size and orientation

Items and Groups

📄 Read: references/items-and-groups.md

• Built-in item types (Button, CheckBox, DropDown, SplitButton, ComboBox, ColorPicker, GroupButton, Template)
• Item properties and icons
• Item sizes (Large, Medium, Small) and active size control
• Item CSS customization with custom classes
• Item tooltips with RibbonTooltipSettings
• Item templates for custom rendering
• Disabled state and display options
• Group orientation (Row vs Column)
• Group overflow behavior and priority

Tabs and Groups Configuration

📄 Read: references/tabs-and-groups.md

• Adding and managing tabs
• Tab-level configuration and CSS customization
• Tab styling with custom classes and themes
• Group properties and organization
• Group headers and icons
• Group collapsibility and launcher icons
• Dynamic tab/group management

Layouts and Display Modes

📄 Read: references/layouts-display-modes.md

• Classic layout (traditional multi-row format)
• Simplified layout (single-row compact format)
• Layout switching and the layout switcher button
• Display options for items (Auto, Classic, Simplified, Overflow)
• Responsive resizing behavior
• Item size adaptation during resizing
• Minimized state (ribbon collapse)

File Menu and Backstage

📄 Read: references/file-menu-backstage.md

• File menu configuration and visibility
• File menu item templates for custom rendering
• File menu popup templates
• File menu animation settings
• File menu tooltip configuration
• Complete event handling (beforeOpen, open, beforeClose, close, beforeItemRender, select)
• Backstage view implementation
• Backstage items configuration with advanced options
• Backstage dimensions (width, height) and positioning
• Backstage KeyTip integration
• Backstage tooltip settings
• Footer items and separators
• Back button customization
• Custom backstage templates
• Navigation within backstage

Contextual Tabs and Gallery

📄 Read: references/contextual-tabs-gallery.md

• Creating contextual tabs
• Controlling contextual tab visibility
• Showing/hiding contextual tabs programmatically
• Gallery item configuration
• Gallery groups and items
• Gallery item templates
• Gallery filtering and selection
• Popup width and height

Events and Accessibility

📄 Read: references/events-accessibility.md

• Ribbon events (itemClick, tabSelected, etc.)
• Event handling and callbacks
• Keyboard shortcuts with KeyTips
• KeyTip configuration
• Accessibility compliance (WCAG)
• ARIA attributes
• Screen reader support
• RTL support
• Focus management
• Keyboard navigation

Customization and Theming

📄 Read: references/customization-theming.md

• Available built-in themes (Material, Bootstrap, Fluent, Tailwind)
• Importing and applying themes
• CSS customization
• Custom icon fonts
• Theme Studio integration
• Dark mode support
• Responsive design considerations
• Custom CSS classes

Tooltips and Help Pane

📄 Read: references/tooltips-help-pane.md

• Tooltip implementation for items
• Custom tooltip templates
• Help pane configuration
• Help pane templates and content
• Contextual help integration

Troubleshooting

📄 Read: references/troubleshooting.md

• Common issues and solutions
• Performance optimization tips
• Styling and display issues
• Event handling problems
• Module injection troubleshooting
• Responsive behavior issues

Quick Start

Basic Ribbon with Tabs and Groups

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective } from "@syncfusion/ej2-react-ribbon";
import "@syncfusion/ej2-base/styles/tailwind3.css";
import "@syncfusion/ej2-buttons/styles/tailwind3.css";
import "@syncfusion/ej2-popups/styles/tailwind3.css";
import "@syncfusion/ej2-splitbuttons/styles/tailwind3.css";
import "@syncfusion/ej2-inputs/styles/tailwind3.css";
import "@syncfusion/ej2-lists/styles/tailwind3.css";
import "@syncfusion/ej2-dropdowns/styles/tailwind3.css";
import "@syncfusion/ej2-navigations/styles/tailwind3.css";
import "@syncfusion/ej2-ribbon/styles/tailwind3.css";

function App() {
  return (
    <RibbonComponent id="ribbon">
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Clipboard">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-copy", content: "Copy" }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-paste", content: "Paste" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

export default App;

Ribbon with File Menu

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective, RibbonFileMenu, Inject } from "@syncfusion/ej2-react-ribbon";
import { MenuItemModel } from '@syncfusion/ej2-navigations';

function App() {
  const fileOptions: MenuItemModel[] = [
    { text: "New", iconCss: "e-icons e-file-new", id: "new" },
    { text: "Open", iconCss: "e-icons e-folder-open", id: "open" },
    { text: "Save", iconCss: "e-icons e-save", id: "save" },
    { text: "Save as", iconCss: "e-icons e-save", id: "saveas" }
  ];

  return (
    <RibbonComponent id="ribbon" fileMenu={{ visible: true, menuItems: fileOptions }}>
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Clipboard">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
      <Inject services={[RibbonFileMenu]} />
    </RibbonComponent>
  );
}

export default App;

Common Patterns

Pattern 1: Multi-Tab Ribbon with Multiple Item Types

Structure a professional ribbon with multiple tabs containing different item types (buttons, dropdowns, combos).

Pattern 2: Responsive Ribbon with Classic and Simplified Layouts

Create a ribbon that switches between Classic (multi-row) and Simplified (single-row) layouts based on screen size or user preference.

Pattern 3: Context-Aware Ribbon

Show/hide contextual tabs dynamically when users select specific objects or content types.

Pattern 4: File Menu with Backstage View

Combine file menu with backstage for comprehensive document management and application settings.

Pattern 5: Gallery-Based Item Selection

Use galleries to provide visual selection of styles, templates, or formatting options.

Key Props and Features

RibbonComponent:

• fileMenu - Configure file menu visibility and items
• backStageMenu - Enable and configure backstage view
• activeLayout - Set layout mode (Classic, Simplified)
• isMinimized - Programmatically minimize/expand ribbon
• hideLayoutSwitcher - Hide the layout switcher button

RibbonTabDirective:

• header - Tab title text
• cssClass - Custom CSS classes for tab styling

RibbonGroupDirective:

• header - Group title
• orientation - Item alignment (Row, Column)
• groupIconCss - Custom icon for group overflow
• showLauncherIcon - Show launcher icon
• enableGroupOverflow - Dedicated overflow popup for group
• isCollapsible - Allow group to collapse on resize
• priority - Collapse/expand priority

RibbonItemDirective:

• type - Item type (Button, CheckBox, DropDown, SplitButton, ComboBox, ColorPicker, GroupButton, Gallery, Template)
• allowedSizes - Permitted item sizes (Large, Medium, Small)
• activeSize - Current display size of the item
• cssClass - Custom CSS classes for item styling
• ribbonTooltipSettings - Tooltip configuration with title and content
• itemTemplate - Custom template for item rendering
• displayOptions - Visibility in layouts (Auto, Classic, Simplified, Overflow)
• disabled - Enable/disable item
• Settings objects: buttonSettings, dropDownSettings, splitButtonSettings, etc.

For complete examples and advanced scenarios, explore individual reference files above.

Contextual Tabs and Gallery Items

Table of Contents

• Contextual Tabs Overview
• Adding Contextual Tabs
• Visibility Control
• Multiple Contextual Tabs
• Gallery Items
• Gallery Configuration
• Gallery Groups

Contextual Tabs Overview

Contextual tabs appear conditionally when users select specific objects (table, image, shape). They provide context-specific commands.

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective, RibbonItemSize, RibbonContextualTab, RibbonContextualTabsDirective, RibbonContextualTabDirective, Inject } from "@syncfusion/ej2-react-ribbon";

function App() {
  return (
    <RibbonComponent id='ribbon'>
      <RibbonTabsDirective>
        <RibbonTabDirective header='Home'>
          {/* Home tab content */}
        </RibbonTabDirective>
      </RibbonTabsDirective>
      <RibbonContextualTabsDirective>
        <RibbonContextualTabDirective visible={true}>
          <RibbonTabsDirective>
            <RibbonTabDirective header='Shape Format' id="ShapeFormat">
              <RibbonGroupsDirective>
                <RibbonGroupDirective header="Text decoration">
                  <RibbonCollectionsDirective>
                    <RibbonCollectionDirective>
                      <RibbonItemsDirective>
                        <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-text-header", content: "Text Header" }}>
                        </RibbonItemDirective>
                      </RibbonItemsDirective>
                    </RibbonCollectionDirective>
                  </RibbonCollectionsDirective>
                </RibbonGroupDirective>
              </RibbonGroupsDirective>
            </RibbonTabDirective>
          </RibbonTabsDirective>
        </RibbonContextualTabDirective>
      </RibbonContextualTabsDirective>
      <Inject services={[RibbonContextualTab]} />
    </RibbonComponent>
  );
}

export default App;

Adding Contextual Tabs

Use RibbonContextualTabsDirective to define contextual tab groups:

<RibbonContextualTabsDirective>
  <RibbonContextualTabDirective visible={true}>
    <RibbonTabsDirective>
      <RibbonTabDirective header='Shape Format' id="ShapeFormat">
        <RibbonGroupsDirective>
          <RibbonGroupDirective header="Shape Styles">
            <RibbonCollectionsDirective>
              <RibbonCollectionDirective>
                <RibbonItemsDirective>
                  <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-format-painter", content: "Format Painter" }}>
                  </RibbonItemDirective>
                </RibbonItemsDirective>
              </RibbonCollectionDirective>
            </RibbonCollectionsDirective>
          </RibbonGroupDirective>
        </RibbonGroupsDirective>
      </RibbonTabDirective>
    </RibbonTabsDirective>
  </RibbonContextualTabDirective>
</RibbonContextualTabsDirective>

Visibility Control

Control when contextual tabs appear:

// Always visible
<RibbonContextualTabDirective visible={true}>
  {/* Tabs */}
</RibbonContextualTabDirective>

// Initially hidden
<RibbonContextualTabDirective visible={false}>
  {/* Tabs */}
</RibbonContextualTabDirective>

// Select tab by default
<RibbonContextualTabDirective visible={true} isSelected={true}>
  {/* Tabs */}
</RibbonContextualTabDirective>

Properties:

• visible - Show/hide contextual tabs (boolean)
• isSelected - Make tab active on initialization (boolean)

Multiple Contextual Tabs

Create multiple contextual tab groups for different object types:

<RibbonContextualTabsDirective>
  {/* Shape contextual tabs */}
  <RibbonContextualTabDirective visible={false} id="shapeContextual">
    <RibbonTabsDirective>
      <RibbonTabDirective header='Shape Format'>
        <RibbonGroupsDirective>
          <RibbonGroupDirective header="Shape Styles">
            {/* Shape-related items */}
          </RibbonGroupDirective>
        </RibbonGroupsDirective>
      </RibbonTabDirective>
    </RibbonTabsDirective>
  </RibbonContextualTabDirective>

  {/* Table contextual tabs */}
  <RibbonContextualTabDirective visible={false} id="tableContextual">
    <RibbonTabsDirective>
      <RibbonTabDirective header='Table Design'>
        <RibbonGroupsDirective>
          <RibbonGroupDirective header="Table Styles">
            {/* Table-related items */}
          </RibbonGroupDirective>
        </RibbonGroupsDirective>
      </RibbonTabDirective>
    </RibbonTabsDirective>
  </RibbonContextualTabDirective>

  {/* Image contextual tabs */}
  <RibbonContextualTabDirective visible={false} id="imageContextual">
    <RibbonTabsDirective>
      <RibbonTabDirective header='Picture Format'>
        <RibbonGroupsDirective>
          <RibbonGroupDirective header="Adjust">
            {/* Image-related items */}
          </RibbonGroupDirective>
        </RibbonGroupsDirective>
      </RibbonTabDirective>
    </RibbonTabsDirective>
  </RibbonContextualTabDirective>
</RibbonContextualTabsDirective>

Gallery Items

Gallery displays visual collections of options (styles, templates, effects).

import { Inject, RibbonGallery, RibbonGallerySettingsModel } from '@syncfusion/ej2-react-ribbon';

const gallerySettings: RibbonGallerySettingsModel = {
  groups: [{
    header: 'Styles',
    items: [
      { content: 'Normal' },
      { content: 'No Spacing' },
      { content: 'Heading 1' },
      { content: 'Heading 2' }
    ]
  }]
};

<RibbonItemDirective type="Gallery" gallerySettings={gallerySettings}>
</RibbonItemDirective>

Gallery Configuration

Configure gallery appearance and behavior:

const gallerySettings: RibbonGallerySettingsModel = {
  groups: [{
    header: 'Styles',
    items: [
      { content: 'Normal' },
      { content: 'No Spacing' },
      { content: 'Heading 1' },
      { content: 'Heading 2' },
      { content: 'Heading 3' }
    ]
  }],
  itemCount: 4,           // Items per row
  popupWidth: '400px',    // Popup width
  popupHeight: '300px'    // Popup height
};

<RibbonItemDirective type="Gallery" gallerySettings={gallerySettings}>
</RibbonItemDirective>

Gallery Settings Properties:

• groups - Array of gallery groups
• itemCount - Items per row in popup (default: 4)
• popupWidth - Width of gallery popup
• popupHeight - Height of gallery popup

Gallery Groups

Organize gallery items into logical groups:

const gallerySettings: RibbonGallerySettingsModel = {
  groups: [
    {
      header: 'Built-in Styles',
      items: [
        { content: 'Normal', iconCss: 'e-icons e-style' },
        { content: 'Heading 1', iconCss: 'e-icons e-header' },
        { content: 'Heading 2', iconCss: 'e-icons e-header' }
      ]
    },
    {
      header: 'Custom Styles',
      items: [
        { content: 'My Style 1' },
        { content: 'My Style 2' },
        { content: 'My Style 3' }
      ]
    }
  ]
};

<RibbonItemDirective type="Gallery" gallerySettings={gallerySettings}>
</RibbonItemDirective>

Gallery Item Properties:

• content - Display text
• iconCss - Icon class (optional)
• disabled - Disable item (boolean)

Complete Contextual Example

import { useRef } from 'react';

function App() {
  let ribbonObj = useRef<RibbonComponent>(null);

  const onImageSelect = () => {
    if (ribbonObj.current) {
      // Show image contextual tabs
      const imageTab = ribbonObj.current.element?.querySelector('[id="imageContextual"]');
      if (imageTab) {
        imageTab.parentElement?.classList.add('show');
      }
    }
  };

  const gallerySettings: RibbonGallerySettingsModel = {
    groups: [{
      header: 'Table Styles',
      items: [
        { content: 'Grid Table 1' },
        { content: 'Grid Table 2' },
        { content: 'Grid Table 3' },
        { content: 'Grid Table 4' }
      ]
    }]
  };

  return (
    <RibbonComponent id='ribbon' ref={ribbonObj}>
      <RibbonTabsDirective>
        <RibbonTabDirective header='Home'>
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Insert">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-image", content: "Image" }} onClick={onImageSelect}>
                    </RibbonItemDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-table", content: "Table" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>

      <RibbonContextualTabsDirective>
        <RibbonContextualTabDirective visible={false} id="imageContextual">
          <RibbonTabsDirective>
            <RibbonTabDirective header='Picture Format'>
              <RibbonGroupsDirective>
                <RibbonGroupDirective header="Adjust">
                  <RibbonCollectionsDirective>
                    <RibbonCollectionDirective>
                      <RibbonItemsDirective>
                        <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-brightness", content: "Brightness" }}>
                        </RibbonItemDirective>
                      </RibbonItemsDirective>
                    </RibbonCollectionDirective>
                  </RibbonCollectionsDirective>
                </RibbonGroupDirective>
              </RibbonGroupsDirective>
            </RibbonTabDirective>
          </RibbonTabsDirective>
        </RibbonContextualTabDirective>

        <RibbonContextualTabDirective visible={false} id="tableContextual">
          <RibbonTabsDirective>
            <RibbonTabDirective header='Table Design'>
              <RibbonGroupsDirective>
                <RibbonGroupDirective header="Table Styles">
                  <RibbonCollectionsDirective>
                    <RibbonCollectionDirective>
                      <RibbonItemsDirective>
                        <RibbonItemDirective type="Gallery" gallerySettings={gallerySettings}>
                        </RibbonItemDirective>
                      </RibbonItemsDirective>
                    </RibbonCollectionDirective>
                  </RibbonCollectionsDirective>
                </RibbonGroupDirective>
              </RibbonGroupsDirective>
            </RibbonTabDirective>
          </RibbonTabsDirective>
        </RibbonContextualTabDirective>
      </RibbonContextualTabsDirective>

      <Inject services={[RibbonContextualTab, RibbonGallery]} />
    </RibbonComponent>
  );
}

export default App;

Best Practices

1. Logical Grouping: Use for object-specific commands 2. Clear Labels: Gallery headers should be descriptive 3. Item Organization: Group gallery items by similarity 4. Performance: Lazy-load contextual tabs if complex 5. Visibility: Control visibility with application state

Customization and Theming

Table of Contents

• Built-in Themes
• Applying Themes
• Theme Switching
• CSS Customization
• Dark Mode
• Custom Icons

Built-in Themes

Syncfusion provides multiple professional themes:

Applying Themes

Import theme CSS in your application:

/* App.css */

/* Material Theme */
@import "../node_modules/@syncfusion/ej2-base/styles/material.css";
@import "../node_modules/@syncfusion/ej2-buttons/styles/material.css";
@import "../node_modules/@syncfusion/ej2-popups/styles/material.css";
@import "../node_modules/@syncfusion/ej2-splitbuttons/styles/material.css";
@import "../node_modules/@syncfusion/ej2-inputs/styles/material.css";
@import "../node_modules/@syncfusion/ej2-lists/styles/material.css";
@import "../node_modules/@syncfusion/ej2-dropdowns/styles/material.css";
@import "../node_modules/@syncfusion/ej2-navigations/styles/material.css";
@import "../node_modules/@syncfusion/ej2-ribbon/styles/material.css";

Or use Tailwind theme:

@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-buttons/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-popups/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-splitbuttons/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-lists/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-dropdowns/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-navigations/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-ribbon/styles/tailwind3.css";

Theme Switching

Switch themes dynamically:

import { useRef, useState } from 'react';
import { RibbonComponent } from "@syncfusion/ej2-react-ribbon";
import "./App.css";

function App() {
  const [theme, setTheme] = useState('material');
  const ribbonRef = useRef<RibbonComponent>(null);

  const switchTheme = (newTheme: string) => {
    setTheme(newTheme);
    
    // Update stylesheets
    const baseLink = document.querySelector('[data-theme-base]');
    const ribbonLink = document.querySelector('[data-theme-ribbon]');
    
    if (baseLink && ribbonLink) {
      baseLink.setAttribute('href', `/styles/${newTheme}/ej2-base.css`);
      ribbonLink.setAttribute('href', `/styles/${newTheme}/ej2-ribbon.css`);
    }
  };

  return (
    <div>
      <div style={{ padding: '10px', marginBottom: '10px' }}>
        <button onClick={() => switchTheme('material')}>Material</button>
        <button onClick={() => switchTheme('bootstrap')}>Bootstrap</button>
        <button onClick={() => switchTheme('fluent')}>Fluent</button>
        <button onClick={() => switchTheme('tailwind3')}>Tailwind</button>
      </div>
      
      <RibbonComponent id="ribbon" ref={ribbonRef}>
        {/* Ribbon content */}
      </RibbonComponent>
    </div>
  );
}

export default App;

CSS Customization

Override theme styles with custom CSS:

/* Custom Ribbon Styles */

/* Override ribbon background */
.e-ribbon {
  background-color: #f5f5f5;
  border-bottom: 2px solid #007bff;
}

/* Override tab header styles */
.e-ribbon .e-tab-header {
  background-color: #ffffff;
  color: #333333;
}

/* Override active tab styles */
.e-ribbon .e-tab-header .e-active {
  background-color: #007bff;
  color: #ffffff;
}

/* Override group header */
.e-ribbon-group-header {
  font-weight: bold;
  color: #555555;
  border-bottom: 1px solid #dddddd;
}

/* Override item buttons */
.e-ribbon .e-btn {
  padding: 8px 12px;
  border-radius: 4px;
}

/* Override item icons */
.e-ribbon .e-icon {
  font-size: 18px;
}

Dark Mode

Implement dark mode support:

import { useEffect, useState } from 'react';
import { RibbonComponent } from "@syncfusion/ej2-react-ribbon";

function App() {
  const [isDarkMode, setIsDarkMode] = useState(false);

  useEffect(() => {
    const root = document.documentElement;
    if (isDarkMode) {
      root.classList.add('dark-mode');
    } else {
      root.classList.remove('dark-mode');
    }
  }, [isDarkMode]);

  return (
    <div>
      <button onClick={() => setIsDarkMode(!isDarkMode)}>
        {isDarkMode ? 'Light Mode' : 'Dark Mode'}
      </button>
      
      <RibbonComponent id="ribbon">
        {/* Ribbon content */}
      </RibbonComponent>
    </div>
  );
}

export default App;

Dark Mode CSS:

/* Dark Mode Styles */
:root.dark-mode {
  --ribbon-bg: #2d2d2d;
  --ribbon-text: #f0f0f0;
  --ribbon-border: #444444;
  --ribbon-hover: #3d3d3d;
}

:root.dark-mode .e-ribbon {
  background-color: var(--ribbon-bg);
  color: var(--ribbon-text);
  border-color: var(--ribbon-border);
}

:root.dark-mode .e-ribbon-tab {
  background-color: var(--ribbon-bg);
  color: var(--ribbon-text);
}

:root.dark-mode .e-ribbon-tab:hover {
  background-color: var(--ribbon-hover);
}

:root.dark-mode .e-ribbon-group-header {
  background-color: var(--ribbon-bg);
  color: var(--ribbon-text);
  border-color: var(--ribbon-border);
}

:root.dark-mode .e-btn {
  background-color: var(--ribbon-bg);
  color: var(--ribbon-text);
  border-color: var(--ribbon-border);
}

:root.dark-mode .e-btn:hover {
  background-color: var(--ribbon-hover);
}

Custom Icons

Use custom icon fonts or SVG icons:

// Using custom icon class
<RibbonItemDirective 
  type="Button" 
  buttonSettings={{ 
    iconCss: "custom-icon-copy",  // Custom CSS class
    content: "Copy" 
  }}>
</RibbonItemDirective>

// Using SVG icons
<RibbonItemDirective 
  type="Button" 
  buttonSettings={{ 
    iconCss: "e-icons e-custom-svg",
    content: "Custom Action" 
  }}>
</RibbonItemDirective>

Custom Icon Styles:

/* Custom Icon Font */
@font-face {
  font-family: 'CustomIcons';
  src: url('/fonts/custom-icons.woff') format('woff');
}

.custom-icon-copy::before {
  font-family: 'CustomIcons';
  content: '\e101';  /* Character code for copy icon */
  font-size: 16px;
}

/* SVG Icons */
.e-custom-svg::before {
  content: url('/icons/custom.svg');
  width: 16px;
  height: 16px;
  display: inline-block;
}

Complete Theme Example

import { useRef, useState } from 'react';
import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective } from "@syncfusion/ej2-react-ribbon";
import "./App.css";

function App() {
  const [isDarkMode, setIsDarkMode] = useState(false);
  const [theme, setTheme] = useState('material');
  const ribbonRef = useRef<RibbonComponent>(null);

  const toggleDarkMode = () => {
    setIsDarkMode(!isDarkMode);
    const root = document.documentElement;
    if (!isDarkMode) {
      root.classList.add('dark-mode');
    } else {
      root.classList.remove('dark-mode');
    }
  };

  const switchTheme = (newTheme: string) => {
    setTheme(newTheme);
    // Update theme stylesheets
    const links = document.querySelectorAll('[data-theme]');
    links.forEach(link => {
      link.setAttribute('href', `/styles/${newTheme}/${link.dataset.theme}.css`);
    });
  };

  return (
    <div>
      <div style={{ padding: '15px', marginBottom: '15px', borderBottom: '1px solid #ddd' }}>
        <div style={{ marginBottom: '10px' }}>
          <strong>Theme:</strong>
          <button onClick={() => switchTheme('material')} style={{ marginLeft: '10px' }}>Material</button>
          <button onClick={() => switchTheme('bootstrap')} style={{ marginLeft: '5px' }}>Bootstrap</button>
          <button onClick={() => switchTheme('fluent')} style={{ marginLeft: '5px' }}>Fluent</button>
        </div>
        
        <div>
          <strong>Mode:</strong>
          <button onClick={toggleDarkMode} style={{ marginLeft: '10px' }}>
            {isDarkMode ? 'Switch to Light' : 'Switch to Dark'}
          </button>
        </div>
      </div>

      <RibbonComponent id="ribbon" ref={ribbonRef}>
        <RibbonTabsDirective>
          <RibbonTabDirective header="Home">
            <RibbonGroupsDirective>
              <RibbonGroupDirective header="Clipboard">
                <RibbonCollectionsDirective>
                  <RibbonCollectionDirective>
                    <RibbonItemsDirective>
                      <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
                      </RibbonItemDirective>
                      <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-copy", content: "Copy" }}>
                      </RibbonItemDirective>
                      <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-paste", content: "Paste" }}>
                      </RibbonItemDirective>
                    </RibbonItemsDirective>
                  </RibbonCollectionDirective>
                </RibbonCollectionsDirective>
              </RibbonGroupDirective>
            </RibbonGroupsDirective>
          </RibbonTabDirective>
        </RibbonTabsDirective>
      </RibbonComponent>
    </div>
  );
}

export default App;

Best Practices

1. Consistency: Use one theme throughout application 2. Accessibility: Ensure dark mode has sufficient contrast 3. Performance: Load only required theme files 4. Custom Icons: Use icon fonts for scalability 5. Testing: Test all themes with various browsers 6. Documentation: Document custom CSS overrides

Events and Accessibility

Table of Contents

• Ribbon Events
• KeyTips (Keyboard Shortcuts)
• KeyTip Configuration
• Accessibility Features
• WCAG Compliance
• RTL Support

Ribbon Events

Handle ribbon interactions through events:

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective } from "@syncfusion/ej2-react-ribbon";
import { useRef } from 'react';

function App() {
  let ribbonObj = useRef<RibbonComponent>(null);

  const onItemClick = (args) => {
    console.log("Item clicked:", args.item);
  };

  const onTabSelected = (args) => {
    console.log("Tab selected:", args.tabIndex);
  };

  return (
    <RibbonComponent 
      id="ribbon"
      ref={ribbonObj}
      itemClick={onItemClick}
      tabSelected={onTabSelected}>
      <RibbonTabsDirective>
        {/* Tabs */}
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

export default App;

Common Events:

• itemClick - When any ribbon item is clicked
• tabSelected - When tab selection changes
• beforeItemRender - Before item rendering
• minimized - When ribbon minimize state changes

KeyTips (Keyboard Shortcuts)

Enable keyboard access to ribbon commands via KeyTips:

<RibbonItemDirective 
  type="Button" 
  keyTip="C"
  buttonSettings={{ 
    iconCss: "e-icons e-copy", 
    content: "Copy" 
  }}>
</RibbonItemDirective>

<RibbonItemDirective 
  type="Button" 
  keyTip="X"
  buttonSettings={{ 
    iconCss: "e-icons e-cut", 
    content: "Cut" 
  }}>
</RibbonItemDirective>

KeyTip Access: 1. Press Alt to display KeyTip letters 2. Type the letter to activate the command

KeyTip Configuration

Configure KeyTip display and behavior:

import { RibbonTabDirective } from "@syncfusion/ej2-react-ribbon";

// Tab with KeyTip
<RibbonTabDirective header="Home" keyTip="H">
  {/* Groups and items */}
</RibbonTabDirective>

// Group with KeyTip
<RibbonGroupDirective header="Clipboard" keyTip="C">
  {/* Items */}
</RibbonGroupDirective>

// Item with KeyTip (already shown above)

KeyTip Best Practices:

• Use intuitive letters (C for Copy, P for Paste)
• Avoid duplicate KeyTips within same context
• Display KeyTips on Alt press for discoverability

Accessibility Features

Implement WCAG-compliant accessibility:

// Provide alt text for icons
<RibbonItemDirective 
  type="Button"
  keyTip="C"
  buttonSettings={{ 
    iconCss: "e-icons e-copy", 
    content: "Copy",
    ariaLabel: "Copy selected content"  // Screen reader text
  }}>
</RibbonItemDirective>

// Use disabled state appropriately
<RibbonItemDirective 
  type="Button"
  disabled={!selectedContent}
  buttonSettings={{ 
    iconCss: "e-icons e-copy", 
    content: "Copy" 
  }}>
</RibbonItemDirective>

// Provide descriptive titles
<RibbonGroupDirective 
  header="Clipboard"
  title="Clipboard commands - Cut, Copy, Paste">
  {/* Items */}
</RibbonGroupDirective>

ARIA Attributes:

• ariaLabel - Descriptive label for screen readers
• role - ARIA role (automatically set)
• aria-disabled - Disabled state indication

WCAG Compliance

Ensure WCAG 2.1 Level AA compliance:

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective } from "@syncfusion/ej2-react-ribbon";

function App() {
  return (
    <RibbonComponent 
      id="ribbon"
      role="toolbar"
      ariaLabel="Main toolbar with formatting and editing commands">
      <RibbonTabsDirective>
        <RibbonTabDirective 
          header="Home" 
          keyTip="H"
          ariaLabel="Home tab with editing commands">
          <RibbonGroupsDirective>
            <RibbonGroupDirective 
              header="Clipboard"
              ariaLabel="Clipboard operations: Cut, Copy, Paste">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective 
                      type="Button"
                      keyTip="X"
                      buttonSettings={{ 
                        iconCss: "e-icons e-cut", 
                        content: "Cut",
                        ariaLabel: "Cut (Ctrl+X)"
                      }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective 
                      type="Button"
                      keyTip="C"
                      buttonSettings={{ 
                        iconCss: "e-icons e-copy", 
                        content: "Copy",
                        ariaLabel: "Copy (Ctrl+C)"
                      }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

export default App;

WCAG Requirements Met:

• Keyboard accessibility (KeyTips, Tab navigation)
• ARIA labels for screen readers
• Color contrast compliance
• Focus indicators
• Semantic HTML structure

RTL Support

Enable right-to-left language support:

<RibbonComponent 
  id="ribbon"
  enableRtl={true}>
  <RibbonTabsDirective>
    {/* Tabs and content - automatically mirrored */}
  </RibbonTabsDirective>
</RibbonComponent>

RTL Behavior:

• All components mirror horizontally
• Text alignment reverses
• Icons position reverses
• Menus expand from right side

Keyboard Navigation

Support full keyboard navigation:

Alt         - Display KeyTips
Arrow Keys  - Navigate tabs and items
Enter       - Activate button/item
Esc         - Close menus
Tab         - Move to next focusable element
Shift+Tab   - Move to previous focusable element

Complete Accessible Example

function App() {
  const handleItemClick = (args) => {
    console.log(`${args.item.content} clicked`);
  };

  const handleTabSelected = (args) => {
    console.log(`Tab ${args.tabIndex} selected`);
  };

  return (
    <RibbonComponent 
      id="ribbon"
      enableRtl={false}
      role="toolbar"
      ariaLabel="Document editing toolbar"
      itemClick={handleItemClick}
      tabSelected={handleTabSelected}>
      
      <RibbonTabsDirective>
        <RibbonTabDirective 
          header="Home" 
          keyTip="H"
          ariaLabel="Home tab">
          <RibbonGroupsDirective>
            <RibbonGroupDirective 
              header="Clipboard"
              ariaLabel="Clipboard operations">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective 
                      type="Button"
                      keyTip="X"
                      buttonSettings={{ 
                        iconCss: "e-icons e-cut", 
                        content: "Cut",
                        ariaLabel: "Cut selected content"
                      }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective 
                      type="Button"
                      keyTip="C"
                      buttonSettings={{ 
                        iconCss: "e-icons e-copy", 
                        content: "Copy",
                        ariaLabel: "Copy selected content"
                      }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective 
                      type="Button"
                      keyTip="V"
                      buttonSettings={{ 
                        iconCss: "e-icons e-paste", 
                        content: "Paste",
                        ariaLabel: "Paste from clipboard"
                      }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

export default App;

Best Practices

1. KeyTips: Provide for all important commands 2. Labels: Use descriptive ARIA labels 3. Contrast: Ensure color contrast ratios meet WCAG AA 4. Keyboard: Support full keyboard navigation 5. Focus: Make focus indicators clearly visible 6. RTL: Test RTL implementations thoroughly 7. Screen Readers: Test with NVDA, JAWS, VoiceOver

File Menu and Backstage View

Table of Contents

• File Menu Basics
• Adding File Menu
• Menu Items Configuration
• File Menu Item Template
• File Menu Popup Template
• File Menu Animation Settings
• File Menu Tooltip Settings
• File Menu Events
• Backstage View
• Backstage Items
• Footer Items
• Backstage Advanced Configuration

File Menu Basics

The Ribbon file menu provides quick access to file-related operations (New, Open, Save, etc.).

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective, RibbonFileMenu, Inject } from "@syncfusion/ej2-react-ribbon";
import { MenuItemModel } from '@syncfusion/ej2-navigations';

function App() {
  const fileOptions: MenuItemModel[] = [
    { text: "New", iconCss: "e-icons e-file-new", id: "new" },
    { text: "Open", iconCss: "e-icons e-folder-open", id: "open" },
    { text: "Save", iconCss: "e-icons e-save", id: "save" },
    { text: "Save as", iconCss: "e-icons e-save", id: "saveas" }
  ];

  return (
    <RibbonComponent id="ribbon" fileMenu={{ visible: true, menuItems: fileOptions }}>
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          {/* Tabs and groups */}
        </RibbonTabDirective>
      </RibbonTabsDirective>
      <Inject services={[RibbonFileMenu]} />
    </RibbonComponent>
  );
}

export default App;

Adding File Menu

Set file menu visibility and configure items:

const fileOptions: MenuItemModel[] = [
  { 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" }
];

<RibbonComponent id="ribbon" fileMenu={{ visible: true, menuItems: fileOptions }}>
  {/* Ribbon content */}
</RibbonComponent>

File Menu Properties:

• visible (boolean) - Show/hide file menu (default: false)
• menuItems (MenuItemModel[]) - Array of menu items

Menu Items Configuration

Define file menu items with text, icons, and submenus:

const fileOptions: MenuItemModel[] = [
  { 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: "saveas",
    items: [
      { text: "Microsoft Word (.docx)", iconCss: "sf-icon-word", id: "newword" },
      { text: "Microsoft Word 97-2003 (.doc)", iconCss: "sf-icon-word", id: "oldword" },
      { text: "Download as PDF", iconCss: "e-icons e-export-pdf", id: "pdf" }
    ]
  }
];

<RibbonComponent id="ribbon" fileMenu={{ visible: true, showItemOnClick: true, menuItems: fileOptions }}>
  {/* Ribbon content */}
</RibbonComponent>

Menu Item Properties:

• text (string) - Menu item text
• iconCss (string) - Icon class
• id (string) - Unique identifier
• items (MenuItemModel[]) - Submenu items
• url (string) - Navigation URL (optional)

Open Submenu on Click:

fileMenu={{ 
  visible: true, 
  showItemOnClick: true,  // Opens on click instead of hover
  menuItems: fileOptions 
}}

File Menu Item Template

Customize the appearance of file menu items using templates:

import { RibbonComponent, RibbonFileMenu, Inject } from "@syncfusion/ej2-react-ribbon";
import { MenuItemModel } from '@syncfusion/ej2-navigations';

function App() {
  const fileOptions: MenuItemModel[] = [
    { text: "New", iconCss: "e-icons e-file-new", id: "new" },
    { text: "Open", iconCss: "e-icons e-folder-open", id: "open" },
    { text: "Save", iconCss: "e-icons e-save", id: "save" }
  ];

  const itemTemplate = (props: any) => {
    return (
      <div style={{ display: 'flex', alignItems: 'center', padding: '8px' }}>
        <span className={props.iconCss} style={{ marginRight: '10px', fontSize: '16px' }}></span>
        <div>
          <div style={{ fontWeight: 'bold' }}>{props.text}</div>
          <div style={{ fontSize: '11px', color: '#666' }}>
            {props.id === 'new' && 'Create a new document'}
            {props.id === 'open' && 'Open an existing document'}
            {props.id === 'save' && 'Save current document'}
          </div>
        </div>
      </div>
    );
  };

  return (
    <RibbonComponent 
      id="ribbon" 
      fileMenu={{ 
        visible: true, 
        menuItems: fileOptions,
        itemTemplate: itemTemplate
      }}>
      <RibbonTabsDirective>
        {/* Tabs */}
      </RibbonTabsDirective>
      <Inject services={[RibbonFileMenu]} />
    </RibbonComponent>
  );
}

export default App;

itemTemplate Property:

• Type: string | function | JSX.Element
• Purpose: Customize rendering of each menu item
• Context: Receives menu item data as props

File Menu Popup Template

Define custom content for the file menu popup area:

import { RibbonComponent, RibbonFileMenu, Inject } from "@syncfusion/ej2-react-ribbon";
import { MenuItemModel } from '@syncfusion/ej2-navigations';

function App() {
  const fileOptions: MenuItemModel[] = [
    { text: "New", iconCss: "e-icons e-file-new", id: "new" },
    { text: "Open", iconCss: "e-icons e-folder-open", id: "open" }
  ];

  const popupTemplate = () => {
    return (
      <div style={{ padding: '20px', width: '300px', backgroundColor: '#f9f9f9' }}>
        <h3 style={{ marginTop: 0 }}>Recent Documents</h3>
        <ul style={{ listStyle: 'none', padding: 0 }}>
          <li style={{ padding: '8px', borderBottom: '1px solid #ddd', cursor: 'pointer' }}>
            <span className="e-icons e-file-new" style={{ marginRight: '8px' }}></span>
            Document1.docx
          </li>
          <li style={{ padding: '8px', borderBottom: '1px solid #ddd', cursor: 'pointer' }}>
            <span className="e-icons e-file-new" style={{ marginRight: '8px' }}></span>
            Document2.docx
          </li>
          <li style={{ padding: '8px', cursor: 'pointer' }}>
            <span className="e-icons e-file-new" style={{ marginRight: '8px' }}></span>
            Document3.docx
          </li>
        </ul>
      </div>
    );
  };

  return (
    <RibbonComponent 
      id="ribbon" 
      fileMenu={{ 
        visible: true, 
        menuItems: fileOptions,
        popupTemplate: popupTemplate
      }}>
      <RibbonTabsDirective>
        {/* Tabs */}
      </RibbonTabsDirective>
      <Inject services={[RibbonFileMenu]} />
    </RibbonComponent>
  );
}

export default App;

popupTemplate Property:

• Type: string | HTMLElement | JSX.Element
• Purpose: Display custom content alongside menu items
• Use Case: Recent files, account info, quick actions

File Menu Animation Settings

Configure animation effects for submenu open/close:

import { RibbonComponent, RibbonFileMenu, Inject } from "@syncfusion/ej2-react-ribbon";
import { MenuItemModel, MenuAnimationSettingsModel } from '@syncfusion/ej2-navigations';

function App() {
  const fileOptions: MenuItemModel[] = [
    { 
      text: "Save as",
      iconCss: "e-icons e-save",
      id: "saveas",
      items: [
        { text: "Microsoft Word (.docx)", id: "docx" },
        { text: "PDF Document (.pdf)", id: "pdf" },
        { text: "Plain Text (.txt)", id: "txt" }
      ]
    },
    { text: "Print", iconCss: "e-icons e-print", id: "print" }
  ];

  const animationSettings: MenuAnimationSettingsModel = {
    effect: 'SlideDown',
    duration: 400,
    easing: 'ease'
  };

  return (
    <RibbonComponent 
      id="ribbon" 
      fileMenu={{ 
        visible: true, 
        menuItems: fileOptions,
        animationSettings: animationSettings
      }}>
      <RibbonTabsDirective>
        {/* Tabs */}
      </RibbonTabsDirective>
      <Inject services={[RibbonFileMenu]} />
    </RibbonComponent>
  );
}

export default App;

Animation Settings Properties:

• effect: Animation type - 'None', 'SlideDown', 'ZoomIn', 'FadeIn'
• duration: Animation duration in milliseconds (default: 400)
• easing: Easing function - 'ease', 'linear', 'ease-in', 'ease-out', 'ease-in-out'

File Menu Tooltip Settings

Add tooltips to the file menu button:

import { RibbonComponent, RibbonFileMenu, Inject } from "@syncfusion/ej2-react-ribbon";
import { MenuItemModel } from '@syncfusion/ej2-navigations';
import { RibbonTooltipModel } from '@syncfusion/ej2-react-ribbon';

function App() {
  const fileOptions: MenuItemModel[] = [
    { text: "New", iconCss: "e-icons e-file-new", id: "new" },
    { text: "Open", iconCss: "e-icons e-folder-open", id: "open" },
    { text: "Save", iconCss: "e-icons e-save", id: "save" }
  ];

  const tooltipSettings: RibbonTooltipModel = {
    title: 'File Menu',
    content: 'Access file operations like New, Open, Save, and Print',
    cssClass: 'custom-tooltip'
  };

  return (
    <RibbonComponent 
      id="ribbon" 
      fileMenu={{ 
        visible: true, 
        menuItems: fileOptions,
        ribbonTooltipSettings: tooltipSettings
      }}>
      <RibbonTabsDirective>
        {/* Tabs */}
      </RibbonTabsDirective>
      <Inject services={[RibbonFileMenu]} />
    </RibbonComponent>
  );
}

export default App;

Tooltip Settings Properties:

• title: Tooltip header text
• content: Tooltip body content
• cssClass: Custom CSS class for styling

File Menu Events

Handle file menu interactions with events:

import { RibbonComponent, RibbonFileMenu, Inject } from "@syncfusion/ej2-react-ribbon";
import { MenuItemModel, FileMenuEventArgs, FileMenuBeforeOpenCloseEventArgs, FileMenuOpenCloseEventArgs } from '@syncfusion/ej2-navigations';

function App() {
  const fileOptions: MenuItemModel[] = [
    { text: "New", iconCss: "e-icons e-file-new", id: "new" },
    { text: "Open", iconCss: "e-icons e-folder-open", id: "open" },
    { text: "Save", iconCss: "e-icons e-save", id: "save" },
    { text: "Print", iconCss: "e-icons e-print", id: "print" }
  ];

  // Event: Before opening file menu
  const handleBeforeOpen = (args: FileMenuBeforeOpenCloseEventArgs) => {
    console.log('File menu is about to open');
    // args.cancel = true; // Uncomment to prevent opening
  };

  // Event: After file menu opens
  const handleOpen = (args: FileMenuOpenCloseEventArgs) => {
    console.log('File menu opened');
  };

  // Event: Before closing file menu
  const handleBeforeClose = (args: FileMenuBeforeOpenCloseEventArgs) => {
    console.log('File menu is about to close');
    // args.cancel = true; // Uncomment to prevent closing
  };

  // Event: After file menu closes
  const handleClose = (args: FileMenuOpenCloseEventArgs) => {
    console.log('File menu closed');
  };

  // Event: Before rendering each menu item
  const handleBeforeItemRender = (args: FileMenuEventArgs) => {
    console.log(`Rendering menu item: ${args.item.text}`);
    // Customize item rendering
    if (args.item.id === 'new') {
      args.element.style.backgroundColor = '#e3f2fd';
    }
  };

  // Event: When menu item is selected
  const handleSelect = (args: FileMenuEventArgs) => {
    console.log(`Menu item selected: ${args.item.text}`);
    
    switch (args.item.id) {
      case 'new':
        console.log('Creating new document...');
        break;
      case 'open':
        console.log('Opening document...');
        break;
      case 'save':
        console.log('Saving document...');
        break;
      case 'print':
        console.log('Printing document...');
        break;
    }
  };

  return (
    <RibbonComponent 
      id="ribbon" 
      fileMenu={{ 
        visible: true, 
        menuItems: fileOptions,
        beforeOpen: handleBeforeOpen,
        open: handleOpen,
        beforeClose: handleBeforeClose,
        close: handleClose,
        beforeItemRender: handleBeforeItemRender,
        select: handleSelect
      }}>
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          {/* Groups and items */}
        </RibbonTabDirective>
      </RibbonTabsDirective>
      <Inject services={[RibbonFileMenu]} />
    </RibbonComponent>
  );
}

export default App;

Available File Menu Events:

Event Arguments Properties:

FileMenuEventArgs:

• element (HTMLElement) - Menu item element
• item (MenuItemModel) - Menu item data

FileMenuBeforeOpenCloseEventArgs:

• cancel (boolean) - Set to true to cancel the action
• element (HTMLElement) - File menu element
• event (Event) - Original browser event

FileMenuOpenCloseEventArgs:

• element (HTMLElement) - File menu element

Complete Event Example

function App() {
  const [isModified, setIsModified] = useState(false);
  const [logs, setLogs] = useState<string[]>([]);

  const fileOptions: MenuItemModel[] = [
    { text: "New", iconCss: "e-icons e-file-new", id: "new" },
    { text: "Save", iconCss: "e-icons e-save", id: "save" },
    { text: "Exit", iconCss: "e-icons e-close", id: "exit" }
  ];

  const handleBeforeClose = (args: FileMenuBeforeOpenCloseEventArgs) => {
    if (isModified) {
      const confirm = window.confirm('You have unsaved changes. Close anyway?');
      if (!confirm) {
        args.cancel = true; // Prevent closing
      }
    }
  };

  const handleSelect = (args: FileMenuEventArgs) => {
    const log = `Selected: ${args.item.text} at ${new Date().toLocaleTimeString()}`;
    setLogs(prev => [...prev, log]);

    if (args.item.id === 'save') {
      setIsModified(false);
    } else if (args.item.id === 'new') {
      setIsModified(true);
    }
  };

  return (
    <div>
      <RibbonComponent 
        id="ribbon" 
        fileMenu={{ 
          visible: true, 
          menuItems: fileOptions,
          beforeClose: handleBeforeClose,
          select: handleSelect
        }}>
        <RibbonTabsDirective>
          {/* Tabs */}
        </RibbonTabsDirective>
        <Inject services={[RibbonFileMenu]} />
      </RibbonComponent>

      <div style={{ marginTop: '20px', padding: '10px', backgroundColor: '#f5f5f5' }}>
        <h4>Event Log:</h4>
        <ul>
          {logs.map((log, index) => (
            <li key={index}>{log}</li>
          ))}
        </ul>
      </div>
    </div>
  );
}

Backstage View

Backstage is a comprehensive replacement for file menu, displaying application settings and information.

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective, RibbonBackstage, Inject, BackStageMenuModel } from "@syncfusion/ej2-react-ribbon";

function App() {
  const backstageSettings: BackStageMenuModel = {
    visible: true,
    items: [
      { 
        id: 'home', 
        text: 'Home', 
        iconCss: 'e-icons e-home', 
        content: "<div style='padding: 20px;'><h2>Welcome to Backstage</h2></div>" 
      },
      { 
        id: 'new', 
        text: 'New', 
        iconCss: 'e-icons e-file-new', 
        content: "<div style='padding: 20px;'><h2>Create New Document</h2></div>" 
      },
      { 
        id: 'open', 
        text: 'Open', 
        iconCss: 'e-icons e-folder-open', 
        content: "<div style='padding: 20px;'><h2>Open Document</h2></div>" 
      }
    ],
    backButton: { text: 'Close' }
  };

  return (
    <RibbonComponent id="ribbon" backStageMenu={backstageSettings}>
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          {/* Tabs and groups */}
        </RibbonTabDirective>
      </RibbonTabsDirective>
      <Inject services={[RibbonBackstage]} />
    </RibbonComponent>
  );
}

export default App;

Backstage Items

Configure backstage items with custom content:

const backstageSettings: BackStageMenuModel = {
  visible: true,
  items: [
    {
      id: 'home',
      text: 'Home',
      iconCss: 'e-icons e-home',
      content: homeContentTemplate()
    },
    {
      id: 'new',
      text: 'New',
      iconCss: 'e-icons e-file-new',
      content: newContentTemplate()
    }
  ],
  backButton: {
    text: 'Close'
  }
};

function homeContentTemplate() {
  return `
    <div id='home-wrapper' style='padding: 20px;'>
      <div id='new-section' class='new-wrapper'>
        <div class='section-title'> New </div>
        <div class='category_container'>
          <div class='doc_category_image'></div>
          <span class='doc_category_text'> New document </span>
        </div>
      </div>
      <div id='block-wrapper'>
        <div class='section-title'> Recent </div>
        <div class='section-content' style='padding: 12px 0px; cursor: pointer'>
          <table>
            <tbody>
              <tr>
                <td> <span class='doc_icon e-icons e-open-link'></span> </td>
                <td>
                  <span style='display: block; font-size: 14px'> Document.docx </span>
                  <span style='font-size: 12px'> Path >> To >> Document </span>
                </td>
              </tr>
            </tbody>
          </table>
        </div>
      </div>
    </div>
  `;
}

Backstage Item Properties:

• id (string) - Unique identifier
• text (string) - Display text
• iconCss (string) - Icon class
• content (string) - HTML content for backstage pane
• isFooter (boolean) - Display as footer item

Footer Items

Add footer items to backstage for account or settings info:

const backstageSettings: BackStageMenuModel = {
  visible: true,
  items: [
    // Regular items
    { id: 'home', text: 'Home', iconCss: 'e-icons e-home', content: homeContent() },
    { id: 'new', text: 'New', iconCss: 'e-icons e-file-new', content: newContent() },
    
    // Separator
    { separator: true, isFooter: true },
    
    // Footer item
    {
      id: 'account',
      text: 'Account',
      isFooter: true,
      content: `
        <div style='padding: 20px;'>
          <div class='section-content' style='padding: 12px 0px;'>
            <table>
              <tbody>
                <tr>
                  <td> <span class='doc_icon e-icons e-people'></span> </td>
                  <td>
                    <span style='display: block; font-size: 14px'>Account type</span>
                    <span style='font-size: 12px'>Administrator</span>
                  </td>
                </tr>
              </tbody>
            </table>
          </div>
        </div>
      `
    }
  ],
  backButton: { text: 'Close' }
};

Separator Item:

• Use { separator: true, isFooter: true } to add visual separator above footer items

Complete Backstage Example

function App() {
  const backstageSettings: BackStageMenuModel = {
    visible: true,
    items: [
      {
        id: 'home',
        text: 'Home',
        iconCss: 'e-icons e-home',
        content: "<div style='padding: 20px;'><p>Welcome to Home</p></div>"
      },
      {
        id: 'new',
        text: 'New',
        iconCss: 'e-icons e-file-new',
        content: "<div style='padding: 20px;'><p>Create New Document</p></div>"
      },
      {
        id: 'open',
        text: 'Open',
        iconCss: 'e-icons e-folder-open',
        content: "<div style='padding: 20px;'><p>Open Existing Document</p></div>"
      },
      { separator: true, isFooter: true },
      {
        id: 'options',
        text: 'Options',
        isFooter: true,
        content: "<div style='padding: 20px;'><p>Application Options</p></div>"
      }
    ],
    backButton: {
      text: 'Close'
    }
  };

  return (
    <RibbonComponent id="ribbon" backStageMenu={backstageSettings}>
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Clipboard">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
      <Inject services={[RibbonBackstage]} />
    </RibbonComponent>
  );
}

export default App;

Backstage Advanced Configuration

Backstage Width and Height

Control the dimensions of the backstage view:

import { RibbonComponent, RibbonBackstage, Inject, BackStageMenuModel } from "@syncfusion/ej2-react-ribbon";

function App() {
  const backstageSettings: BackStageMenuModel = {
    visible: true,
    width: '600px',    // Custom width
    height: '500px',   // Custom height
    items: [
      { 
        id: 'home', 
        text: 'Home', 
        iconCss: 'e-icons e-home', 
        content: "<div style='padding: 20px;'><h2>Home</h2></div>" 
      },
      { 
        id: 'settings', 
        text: 'Settings', 
        iconCss: 'e-icons e-settings', 
        content: "<div style='padding: 20px;'><h2>Settings</h2></div>" 
      }
    ],
    backButton: { text: 'Close' }
  };

  return (
    <RibbonComponent id="ribbon" backStageMenu={backstageSettings}>
      <RibbonTabsDirective>
        {/* Tabs */}
      </RibbonTabsDirective>
      <Inject services={[RibbonBackstage]} />
    </RibbonComponent>
  );
}

export default App;

Dimension Properties:

• width: Width of backstage menu (string, e.g., '600px', '50%')
• height: Height of backstage menu (string, e.g., '500px', '80vh')

Backstage Target Element

Position backstage within a specific element:

import { RibbonComponent, RibbonBackstage, Inject, BackStageMenuModel } from "@syncfusion/ej2-react-ribbon";

function App() {
  const backstageSettings: BackStageMenuModel = {
    visible: true,
    target: '#backstage-container',  // CSS selector for target element
    items: [
      { 
        id: 'home', 
        text: 'Home', 
        iconCss: 'e-icons e-home', 
        content: "<div style='padding: 20px;'><h2>Welcome</h2></div>" 
      }
    ],
    backButton: { text: 'Close' }
  };

  return (
    <div>
      <RibbonComponent id="ribbon" backStageMenu={backstageSettings}>
        <RibbonTabsDirective>
          {/* Tabs */}
        </RibbonTabsDirective>
        <Inject services={[RibbonBackstage]} />
      </RibbonComponent>

      {/* Target container for backstage */}
      <div id="backstage-container" style={{ 
        position: 'relative', 
        width: '100%', 
        height: '600px',
        border: '1px solid #ddd'
      }}>
        {/* Backstage will be positioned here */}
      </div>
    </div>
  );
}

export default App;

target Property:

• Type: string | HTMLElement
• Purpose: Defines element for backstage positioning
• Default: Document body

Backstage KeyTip

Add keyboard shortcut access to backstage:

import { RibbonComponent, RibbonBackstage, RibbonKeyTip, Inject, BackStageMenuModel } from "@syncfusion/ej2-react-ribbon";

function App() {
  const backstageSettings: BackStageMenuModel = {
    visible: true,
    text: 'File',
    keyTip: 'F',  // Press Alt+F to open backstage
    items: [
      { 
        id: 'new', 
        text: 'New', 
        iconCss: 'e-icons e-file-new',
        keyTip: 'N',  // Press N after opening backstage
        content: "<div style='padding: 20px;'><h2>Create New</h2></div>" 
      },
      { 
        id: 'open', 
        text: 'Open', 
        iconCss: 'e-icons e-folder-open',
        keyTip: 'O',
        content: "<div style='padding: 20px;'><h2>Open File</h2></div>" 
      }
    ],
    backButton: { text: 'Close' }
  };

  return (
    <RibbonComponent id="ribbon" enableKeyTips={true} backStageMenu={backstageSettings}>
      <RibbonTabsDirective>
        {/* Tabs */}
      </RibbonTabsDirective>
      <Inject services={[RibbonBackstage, RibbonKeyTip]} />
    </RibbonComponent>
  );
}

export default App;

KeyTip Properties:

• keyTip (backstage button): Keyboard shortcut for opening backstage
• keyTip (backstage items): Keyboard shortcuts for navigation within backstage
• Requires: enableKeyTips={true} on RibbonComponent and RibbonKeyTip service injection

Backstage Tooltip Settings

Add tooltips to the backstage button:

import { RibbonComponent, RibbonBackstage, Inject, BackStageMenuModel } from "@syncfusion/ej2-react-ribbon";
import { RibbonTooltipModel } from '@syncfusion/ej2-react-ribbon';

function App() {
  const tooltipSettings: RibbonTooltipModel = {
    title: 'Backstage',
    content: 'Access file operations, settings, and account information',
    cssClass: 'backstage-tooltip'
  };

  const backstageSettings: BackStageMenuModel = {
    visible: true,
    text: 'File',
    ribbonTooltipSettings: tooltipSettings,
    items: [
      { 
        id: 'home', 
        text: 'Home', 
        iconCss: 'e-icons e-home', 
        content: "<div style='padding: 20px;'><h2>Home</h2></div>" 
      }
    ],
    backButton: { text: 'Close' }
  };

  return (
    <RibbonComponent id="ribbon" backStageMenu={backstageSettings}>
      <RibbonTabsDirective>
        {/* Tabs */}
      </RibbonTabsDirective>
      <Inject services={[RibbonBackstage]} />
    </RibbonComponent>
  );
}

export default App;

ribbonTooltipSettings Properties:

• title: Tooltip header
• content: Tooltip description
• cssClass: Custom CSS class for styling

Backstage Template

Use a custom template for backstage content:

import { RibbonComponent, RibbonBackstage, Inject, BackStageMenuModel } from "@syncfusion/ej2-react-ribbon";

function App() {
  const backstageTemplate = () => {
    return (
      <div style={{ display: 'flex', height: '100%' }}>
        <div style={{ width: '200px', backgroundColor: '#f0f0f0', padding: '20px' }}>
          <h3>Navigation</h3>
          <ul style={{ listStyle: 'none', padding: 0 }}>
            <li style={{ padding: '10px', cursor: 'pointer' }}>New</li>
            <li style={{ padding: '10px', cursor: 'pointer' }}>Open</li>
            <li style={{ padding: '10px', cursor: 'pointer' }}>Save</li>
          </ul>
        </div>
        <div style={{ flex: 1, padding: '20px' }}>
          <h2>Welcome to Backstage</h2>
          <p>Select an option from the navigation menu.</p>
        </div>
      </div>
    );
  };

  const backstageSettings: BackStageMenuModel = {
    visible: true,
    text: 'File',
    template: backstageTemplate,  // Custom template overrides items
    backButton: { text: 'Close' }
  };

  return (
    <RibbonComponent id="ribbon" backStageMenu={backstageSettings}>
      <RibbonTabsDirective>
        {/* Tabs */}
      </RibbonTabsDirective>
      <Inject services={[RibbonBackstage]} />
    </RibbonComponent>
  );
}

export default App;

template Property:

• Type: string | function | JSX.Element
• Purpose: Completely custom backstage content
• Note: When template is used, items property is ignored

Complete Backstage Configuration Example

import { RibbonComponent, RibbonBackstage, RibbonKeyTip, Inject, BackStageMenuModel } from "@syncfusion/ej2-react-ribbon";
import { RibbonTooltipModel } from '@syncfusion/ej2-react-ribbon';

function App() {
  const tooltipSettings: RibbonTooltipModel = {
    title: 'File Menu',
    content: 'Manage your documents and settings'
  };

  const backstageSettings: BackStageMenuModel = {
    visible: true,
    text: 'File',
    width: '700px',
    height: '600px',
    keyTip: 'F',
    ribbonTooltipSettings: tooltipSettings,
    items: [
      { 
        id: 'home', 
        text: 'Home', 
        iconCss: 'e-icons e-home',
        keyTip: 'H',
        content: `
          <div style='padding: 20px;'>
            <h2>Welcome</h2>
            <div style='display: grid; grid-template-columns: repeat(3, 1fr); gap: 20px; margin-top: 20px;'>
              <div style='padding: 15px; border: 1px solid #ddd; border-radius: 4px; cursor: pointer;'>
                <h3>New Document</h3>
                <p>Create a blank document</p>
              </div>
              <div style='padding: 15px; border: 1px solid #ddd; border-radius: 4px; cursor: pointer;'>
                <h3>From Template</h3>
                <p>Start with a template</p>
              </div>
              <div style='padding: 15px; border: 1px solid #ddd; border-radius: 4px; cursor: pointer;'>
                <h3>Recent</h3>
                <p>Open recent documents</p>
              </div>
            </div>
          </div>
        `
      },
      { 
        id: 'open', 
        text: 'Open', 
        iconCss: 'e-icons e-folder-open',
        keyTip: 'O',
        content: "<div style='padding: 20px;'><h2>Open Document</h2><p>Browse and open files.</p></div>" 
      },
      { 
        id: 'save', 
        text: 'Save As', 
        iconCss: 'e-icons e-save',
        keyTip: 'A',
        content: "<div style='padding: 20px;'><h2>Save As</h2><p>Save your document to a location.</p></div>" 
      },
      { separator: true, isFooter: true },
      {
        id: 'settings',
        text: 'Settings',
        iconCss: 'e-icons e-settings',
        keyTip: 'S',
        isFooter: true,
        content: "<div style='padding: 20px;'><h2>Application Settings</h2></div>"
      }
    ],
    backButton: { text: 'Close' }
  };

  return (
    <RibbonComponent id="ribbon" enableKeyTips={true} backStageMenu={backstageSettings}>
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          {/* Groups and items */}
        </RibbonTabDirective>
      </RibbonTabsDirective>
      <Inject services={[RibbonBackstage, RibbonKeyTip]} />
    </RibbonComponent>
  );
}

export default App;

Best Practices

1. Logical Organization: Group related file operations 2. Clear Icons: Use consistent, recognizable icons 3. Navigation: Use url property for navigation items 4. Content: Keep backstage content organized and scannable 5. Footer: Use for account and settings items 6. Dimensions: Set appropriate width/height for your content 7. KeyTips: Provide keyboard shortcuts for accessibility 8. Tooltips: Add helpful tooltips to the backstage button 9. Templates: Use custom templates for complex layouts 10. Performance: Keep backstage content lightweight for fast loading

Getting Started with Syncfusion React Ribbon

Table of Contents

• Installation
• Setup Project
• Add Styles
• Create Basic Ribbon
• Module Injection
• Run Application

Installation

Install the Ribbon component package via npm:

npm install @syncfusion/ej2-react-ribbon --save

Project Setup

For a new React TypeScript project, use Vite (recommended for faster development):

npm create vite@latest my-ribbon-app -- --template react-ts
cd my-ribbon-app
npm run dev

For JavaScript only:

npm create vite@latest my-ribbon-app -- --template react
cd my-ribbon-app
npm run dev

Add Styles

Import the Ribbon styles into your application. Open src/App.css and add the following imports:

@import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-buttons/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-popups/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-splitbuttons/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-lists/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-dropdowns/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-navigations/styles/tailwind3.css";
@import "../node_modules/@syncfusion/ej2-ribbon/styles/tailwind3.css";

Available Theme Files:

• material.css - Material Design theme
• bootstrap.css - Bootstrap theme
• bootstrap4.css - Bootstrap 4 theme
• fluent.css - Fluent Design theme
• tailwind3.css - Tailwind CSS theme (recommended)

Choose the theme file that matches your application's design system.

Create Basic Ribbon

Open src/App.tsx and create a basic Ribbon component:

import { RibbonComponent } from "@syncfusion/ej2-react-ribbon";
import "./App.css";

function App() {
  return (
    <RibbonComponent id="ribbon"></RibbonComponent>
  );
}

export default App;

This creates an empty Ribbon. To add functionality, you need to define tabs and groups (see ribbon-structure.md).

Module Injection

Some Ribbon features require module injection. Use the Inject component to register services:

import { RibbonComponent, RibbonFileMenu, RibbonColorPicker, Inject } from "@syncfusion/ej2-react-ribbon";

function App() {
  return (
    <RibbonComponent id="ribbon">
      <Inject services={[RibbonFileMenu, RibbonColorPicker]} />
    </RibbonComponent>
  );
}

export default App;

Available services for injection:

• RibbonFileMenu - File menu feature
• RibbonColorPicker - Color picker item
• RibbonContextualTab - Contextual tab feature
• RibbonGallery - Gallery item type
• RibbonBackstage - Backstage view (if using file menu with backstage)

Complete Minimal Example

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective } from "@syncfusion/ej2-react-ribbon";
import "./App.css";

function App() {
  return (
    <RibbonComponent id="ribbon">
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Clipboard">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-copy", content: "Copy" }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-paste", content: "Paste" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

export default App;

Run Application

Start the development server:

npm run dev

The Ribbon component is now running. Navigate to the provided local URL (typically http://localhost:5173).

TypeScript Configuration

Syncfusion components have full TypeScript support. For a React TypeScript project, type definitions are automatically included. Ensure your tsconfig.json has proper React settings:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "target": "ES2020",
    "lib": ["ES2020", "DOM", "DOM.Iterable"]
  }
}

Troubleshooting

Styles not applying:

• Verify all CSS imports are correct in App.css
• Check that the theme file path matches your node_modules structure
• Ensure CSS is imported before creating components

Components not rendering:

• Verify all required imports are included
• Check that Ribbon ID is unique
• Ensure parent HTML element with id="element" or similar exists

Module not found errors:

• Run npm install to ensure
• Clear node_modules and reinstall: rm -rf node_modules && npm install

Items and Groups Configuration

Table of Contents

• Item Types Overview
• Button Items
• CheckBox Items
• DropDown Items
• SplitButton Items
• ComboBox Items
• ColorPicker Items
• GroupButton Items
• Template Items
• Item Display Options
• Item Sizing
• Item Active Size
• Item CSS Customization
• Item Tooltips
• Item Template for Custom Items
• Enable or Disable Items
• Group Configuration
• Group Orientation

Item Types Overview

The Ribbon supports the following built-in item types:

Button Items

Basic button item with icon and click handling:

import { RibbonItemDirective, RibbonItemSize } from "@syncfusion/ej2-react-ribbon";

<RibbonItemDirective type="Button" 
  buttonSettings={{ 
    iconCss: "e-icons e-cut", 
    content: "Cut" 
  }}>
</RibbonItemDirective>

Button with Toggle Behavior:

<RibbonItemDirective type="Button" 
  buttonSettings={{ 
    iconCss: "e-icons e-bold", 
    content: "Bold", 
    isToggle: true 
  }}>
</RibbonItemDirective>

Button Properties:

• content - Button text
• iconCss - Icon class (e.g., "e-icons e-cut")
• isToggle - True for toggle button behavior (boolean)
• disabled - Disable the button (boolean)

CheckBox Items

Checkbox for binary selection:

<RibbonItemDirective type="CheckBox" 
  checkBoxSettings={{ 
    label: "Ruler", 
    checked: true 
  }}>
</RibbonItemDirective>

With Label Position:

<RibbonItemDirective type="CheckBox" 
  checkBoxSettings={{ 
    label: "Ruler", 
    labelPosition: "Before", 
    checked: false 
  }}>
</RibbonItemDirective>

CheckBox Properties:

• label - Text label for checkbox
• labelPosition - "Before" or "After" (default: "After")
• checked - Initial checked state (boolean)

DropDown Items

Dropdown button with menu options:

import { ItemModel } from "@syncfusion/ej2-splitbuttons";

const tableOptions: ItemModel[] = [
  { text: "Insert Table" },
  { text: "This device" },
  { text: "Convert Table" },
  { text: "Excel SpreadSheet" }
];

<RibbonItemDirective type="DropDown" 
  dropDownSettings={{ 
    iconCss: "e-icons e-table", 
    items: tableOptions, 
    content: "Table" 
  }}>
</RibbonItemDirective>

DropDown with beforeItemRender Event:

import { MenuEventArgs } from "@syncfusion/ej2-splitbuttons";

<RibbonItemDirective type="DropDown" 
  dropDownSettings={{ 
    iconCss: "e-icons e-table", 
    items: tableOptions, 
    content: "Table",
    beforeItemRender: function (args: MenuEventArgs) {
      if (args.item.text === 'Insert Table') {
        args.element.classList.add("e-custom-class");
      }
    }
  }}>
</RibbonItemDirective>

On-Demand Popup Creation:

<RibbonItemDirective type="DropDown" 
  dropDownSettings={{ 
    iconCss: "e-icons e-table", 
    items: tableOptions, 
    content: "Table",
    createPopupOnClick: true
  }}>
</RibbonItemDirective>

DropDown Properties:

• items - Array of menu items (ItemModel[])
• content - Button text
• iconCss - Icon class
• target - Selector for custom popup content (optional)
• beforeItemRender - Event for customizing dropdown items
• createPopupOnClick - Create popup only on click (boolean)

SplitButton Items

Button with primary action and dropdown options:

const pasteOptions: ItemModel[] = [
  { text: "Keep Source Format" },
  { text: "Merge format" },
  { text: "Keep text only" }
];

<RibbonItemDirective type="SplitButton" 
  allowedSizes={RibbonItemSize.Large}
  splitButtonSettings={{ 
    iconCss: "e-icons e-paste", 
    items: pasteOptions, 
    content: "Paste" 
  }}>
</RibbonItemDirective>

SplitButton with Target:

<RibbonItemDirective type="SplitButton" 
  splitButtonSettings={{ 
    iconCss: "e-icons e-image", 
    content: "Pictures", 
    target: "#pictureList" 
  }}>
</RibbonItemDirective>

SplitButton Properties:

• items - Array of dropdown options
• content - Button text
• iconCss - Icon class
• target - Selector for custom popup (optional)

ComboBox Items

Text input with dropdown list:

const fontStyle: string[] = ["Algerian", "Arial", "Calibri", "Cambria", "Georgia"];

<RibbonItemDirective type="ComboBox" 
  comboBoxSettings={{ 
    dataSource: fontStyle, 
    index: 1, 
    width: "150px", 
    allowFiltering: true 
  }}>
</RibbonItemDirective>

With Sorting:

<RibbonItemDirective type="ComboBox" 
  comboBoxSettings={{ 
    dataSource: fontStyle, 
    index: 1, 
    width: "150px", 
    allowFiltering: true,
    sortOrder: "Descending"
  }}>
</RibbonItemDirective>

ComboBox Properties:

• dataSource - Array of items
• index - Initially selected index
• width - ComboBox width (string, e.g., "150px")
• allowFiltering - Enable filtering (boolean)
• sortOrder - "None", "Ascending", or "Descending"

ColorPicker Items

Color selection control:

import { RibbonColorPicker, Inject } from "@syncfusion/ej2-react-ribbon";

<RibbonItemDirective type="ColorPicker" 
  colorPickerSettings={{ 
    value: "#123456" 
  }}>
</RibbonItemDirective>

Note: ColorPicker requires module injection:

<Inject services={[RibbonColorPicker]} />

ColorPicker Properties:

• value - Initial color value (hex code)
• columns - Number of color columns
• showButtons - Show OK/Cancel buttons (boolean)

GroupButton Items

Group of related buttons:

import { RibbonGroupButtonSelection, RibbonGroupButtonSettingsModel } from "@syncfusion/ej2-react-ribbon";

const groupButtonItem: RibbonGroupButtonSettingsModel = {
  selection: RibbonGroupButtonSelection.Single,
  items: [
    { iconCss: 'e-icons e-align-left', selected: true, content: 'Align Left' },
    { iconCss: 'e-icons e-align-center', content: 'Align Center' },
    { iconCss: 'e-icons e-align-right', content: 'Align Right' },
    { iconCss: 'e-icons e-justify', content: 'Justify' }
  ]
};

<RibbonItemDirective type="GroupButton" 
  allowedSizes={RibbonItemSize.Medium}
  groupButtonSettings={groupButtonItem}>
</RibbonItemDirective>

Multiple Selection:

const groupButtonItem: RibbonGroupButtonSettingsModel = {
  selection: RibbonGroupButtonSelection.Multiple,
  items: [
    { iconCss: 'e-icons e-bold', content: 'Bold', selected: true },
    { iconCss: 'e-icons e-italic', content: 'Italic' },
    { iconCss: 'e-icons e-underline', content: 'Underline' }
  ]
};

GroupButton Properties:

• items - Array of button items
• selection - "Single" or "Multiple"
• Individual item properties:
• iconCss - Icon class (required)
• content - Button text
• selected - Initially selected state (boolean)

Template Items

Custom HTML/React content:

<RibbonItemDirective type="Template" 
  itemTemplate={(props: any) => {
    return (
      <span className="ribbonTemplate">
        <span className="e-icons e-video"></span>
        <span className="text">Video</span>
      </span>
    );
  }}>
</RibbonItemDirective>

Template with Custom Controls:

<RibbonItemDirective type="Template" 
  itemTemplate={(props: any) => {
    return (
      <div className="custom-template">
        <label htmlFor="fname">First name:</label>
        <input type="text" id="fname" name="fname"/>
        <br/>
        <label htmlFor="lname">Last name:</label>
        <input type="text" id="lname" name="lname"/>
      </div>
    );
  }}>
</RibbonItemDirective>

Item Display Options

Control where items appear in different layouts:

import { DisplayMode } from "@syncfusion/ej2-react-ribbon";

// Display only in Classic layout
<RibbonItemDirective type="Button" 
  displayOptions={DisplayMode.Classic}
  buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
</RibbonItemDirective>

// Display only in Simplified layout
<RibbonItemDirective type="Button" 
  displayOptions={DisplayMode.Simplified}
  buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
</RibbonItemDirective>

// Display only in overflow popup
<RibbonItemDirective type="Button" 
  displayOptions={DisplayMode.Overflow}
  buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
</RibbonItemDirective>

Available Options:

• DisplayMode.Auto - (Default) Display in all layouts
• DisplayMode.Classic - Classic layout only
• DisplayMode.Simplified - Simplified layout only
• DisplayMode.Overflow - Overflow popup only

Item Sizing

Control item size with allowedSizes:

import { RibbonItemSize } from "@syncfusion/ej2-react-ribbon";

// Large size
<RibbonItemDirective type="SplitButton" 
  allowedSizes={RibbonItemSize.Large}
  splitButtonSettings={{ content: "Paste" }}>
</RibbonItemDirective>

// Medium size
<RibbonItemDirective type="Button" 
  allowedSizes={RibbonItemSize.Medium}
  buttonSettings={{ content: "Copy" }}>
</RibbonItemDirective>

// Small size
<RibbonItemDirective type="Button" 
  allowedSizes={RibbonItemSize.Small}
  buttonSettings={{ content: "Cut" }}>
</RibbonItemDirective>

Size Effects:

• Large: Large icon with text below
• Medium: Small icon with text beside
• Small: Small icon only

Items resize automatically during ribbon resizing: Large → Medium → Small

Item Active Size

Control the current active size of a ribbon item programmatically:

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective, RibbonItemSize } from "@syncfusion/ej2-react-ribbon";
import { useRef, useState } from 'react';

function App() {
  const [currentSize, setCurrentSize] = useState<RibbonItemSize>(RibbonItemSize.Large);

  const changeToCut = () => {
    setCurrentSize(RibbonItemSize.Medium);
  };

  return (
    <div>
      <button onClick={changeToCut}>Change to Medium Size</button>
      
      <RibbonComponent id="ribbon">
        <RibbonTabsDirective>
          <RibbonTabDirective header="Home">
            <RibbonGroupsDirective>
              <RibbonGroupDirective header="Clipboard">
                <RibbonCollectionsDirective>
                  <RibbonCollectionDirective>
                    <RibbonItemsDirective>
                      <RibbonItemDirective 
                        type="Button" 
                        activeSize={currentSize}
                        allowedSizes={RibbonItemSize.Large | RibbonItemSize.Medium | RibbonItemSize.Small}
                        buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
                      </RibbonItemDirective>
                    </RibbonItemsDirective>
                  </RibbonCollectionDirective>
                </RibbonCollectionsDirective>
              </RibbonGroupDirective>
            </RibbonGroupsDirective>
          </RibbonTabDirective>
        </RibbonTabsDirective>
      </RibbonComponent>
    </div>
  );
}

export default App;

activeSize Property:

• Type: RibbonItemSize
• Purpose: Sets the current display size of the item
• Values: RibbonItemSize.Large, RibbonItemSize.Medium, RibbonItemSize.Small
• Note: Must be one of the sizes specified in allowedSizes

Dynamic Size Control:

import { useRef } from 'react';

function App() {
  const ribbonRef = useRef<RibbonComponent>(null);

  const setItemSize = (itemId: string, size: RibbonItemSize) => {
    if (ribbonRef.current) {
      // Access item and update its active size
      const item = ribbonRef.current.element?.querySelector(`[id="${itemId}"]`);
      if (item) {
        // Update via component API
        console.log(`Setting ${itemId} to ${size}`);
      }
    }
  };

  return (
    <RibbonComponent id="ribbon" ref={ribbonRef}>
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Clipboard">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective 
                      type="Button" 
                      id="cutButton"
                      activeSize={RibbonItemSize.Large}
                      allowedSizes={RibbonItemSize.Large | RibbonItemSize.Medium}
                      buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

Use Cases:

• Force specific item size regardless of ribbon width
• Maintain consistent sizing for important items
• Override automatic size adaptation
• Control item appearance programmatically

Item CSS Customization

Apply custom CSS classes to individual items:

import { RibbonItemDirective } from "@syncfusion/ej2-react-ribbon";

// Single custom class
<RibbonItemDirective 
  type="Button" 
  cssClass="custom-button"
  buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
</RibbonItemDirective>

// Multiple classes
<RibbonItemDirective 
  type="Button" 
  cssClass="custom-button highlight-item"
  buttonSettings={{ iconCss: "e-icons e-copy", content: "Copy" }}>
</RibbonItemDirective>

// Conditional styling
<RibbonItemDirective 
  type="Button" 
  cssClass={isImportant ? "important-action" : "normal-action"}
  buttonSettings={{ iconCss: "e-icons e-save", content: "Save" }}>
</RibbonItemDirective>

CSS Styling Example:

/* Custom button styles */
.custom-button .e-btn {
  background-color: #007bff;
  color: white;
  border-radius: 6px;
  font-weight: bold;
}

.custom-button .e-btn:hover {
  background-color: #0056b3;
}

/* Highlight important items */
.highlight-item {
  border: 2px solid #ffc107;
  padding: 2px;
  border-radius: 4px;
}

/* Important action styling */
.important-action .e-btn {
  background-color: #dc3545;
  color: white;
}

.important-action .e-btn:hover {
  background-color: #c82333;
}

/* Normal action styling */
.normal-action .e-btn {
  background-color: #6c757d;
  color: white;
}

Complete Example with Custom Styling:

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective } from "@syncfusion/ej2-react-ribbon";
import './customStyles.css';

function App() {
  return (
    <RibbonComponent id="ribbon">
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Actions">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    {/* Primary action with custom style */}
                    <RibbonItemDirective 
                      type="Button" 
                      cssClass="primary-action"
                      buttonSettings={{ 
                        iconCss: "e-icons e-save", 
                        content: "Save" 
                      }}>
                    </RibbonItemDirective>

                    {/* Secondary action */}
                    <RibbonItemDirective 
                      type="Button" 
                      cssClass="secondary-action"
                      buttonSettings={{ 
                        iconCss: "e-icons e-cut", 
                        content: "Cut" 
                      }}>
                    </RibbonItemDirective>

                    {/* Danger action */}
                    <RibbonItemDirective 
                      type="Button" 
                      cssClass="danger-action"
                      buttonSettings={{ 
                        iconCss: "e-icons e-trash", 
                        content: "Delete" 
                      }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

export default App;

cssClass Property:

• Type: string
• Purpose: Apply custom CSS classes to the item container
• Use Cases: Custom styling, theme overrides, visual emphasis, conditional styling

Item Tooltips

Add detailed tooltips to ribbon items using ribbonTooltipSettings:

import { RibbonItemDirective } from "@syncfusion/ej2-react-ribbon";
import { RibbonTooltipModel } from '@syncfusion/ej2-react-ribbon';

// Basic tooltip
<RibbonItemDirective 
  type="Button" 
  ribbonTooltipSettings={{ 
    title: 'Cut', 
    content: 'Remove selected content and place it on the clipboard' 
  }}
  buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
</RibbonItemDirective>

// Tooltip with keyboard shortcut
<RibbonItemDirective 
  type="Button" 
  ribbonTooltipSettings={{ 
    title: 'Copy', 
    content: 'Copy selected content to clipboard (Ctrl+C)',
    cssClass: 'custom-tooltip'
  }}
  buttonSettings={{ iconCss: "e-icons e-copy", content: "Copy" }}>
</RibbonItemDirective>

// Detailed tooltip
<RibbonItemDirective 
  type="SplitButton" 
  ribbonTooltipSettings={{ 
    title: 'Paste Options', 
    content: 'Insert content from clipboard. Click the arrow for paste options.'
  }}
  splitButtonSettings={{ 
    iconCss: "e-icons e-paste", 
    content: "Paste",
    items: [
      { text: "Keep Source Formatting" },
      { text: "Merge Formatting" },
      { text: "Keep Text Only" }
    ]
  }}>
</RibbonItemDirective>

RibbonTooltipModel Properties:

• title: Tooltip header text (string)
• content: Tooltip body/description (string)
• cssClass: Custom CSS class for styling (string)

Advanced Tooltip Example:

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective, RibbonItemSize } from "@syncfusion/ej2-react-ribbon";
import { RibbonTooltipModel } from '@syncfusion/ej2-react-ribbon';

function App() {
  const cutTooltip: RibbonTooltipModel = {
    title: 'Cut',
    content: 'Remove the selection and put it on the Clipboard so you can paste it somewhere else.',
    cssClass: 'ribbon-tooltip'
  };

  const copyTooltip: RibbonTooltipModel = {
    title: 'Copy',
    content: 'Put a copy of the selection on the Clipboard so you can paste it somewhere else.',
    cssClass: 'ribbon-tooltip'
  };

  const pasteTooltip: RibbonTooltipModel = {
    title: 'Paste',
    content: 'Insert the content from the Clipboard at the current location.',
    cssClass: 'ribbon-tooltip'
  };

  return (
    <RibbonComponent id="ribbon">
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Clipboard">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective 
                      type="SplitButton" 
                      allowedSizes={RibbonItemSize.Large}
                      ribbonTooltipSettings={pasteTooltip}
                      splitButtonSettings={{ 
                        iconCss: "e-icons e-paste", 
                        content: "Paste",
                        items: [
                          { text: "Keep Source Formatting" },
                          { text: "Merge Formatting" }
                        ]
                      }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective 
                      type="Button" 
                      ribbonTooltipSettings={cutTooltip}
                      buttonSettings={{ 
                        iconCss: "e-icons e-cut", 
                        content: "Cut" 
                      }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective 
                      type="Button" 
                      ribbonTooltipSettings={copyTooltip}
                      buttonSettings={{ 
                        iconCss: "e-icons e-copy", 
                        content: "Copy" 
                      }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

export default App;

Custom Tooltip Styling:

/* Custom tooltip styles */
.ribbon-tooltip.e-tooltip-wrap {
  background-color: #2d3748;
  color: #ffffff;
  border-radius: 6px;
  padding: 12px;
  max-width: 300px;
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
}

.ribbon-tooltip .e-tip-content {
  font-size: 13px;
  line-height: 1.5;
}

.ribbon-tooltip .e-arrow-tip-outer {
  border-top-color: #2d3748;
}

Tooltip with HTML Content:

const advancedTooltip: RibbonTooltipModel = {
  title: 'Format Painter',
  content: `
    <div style="padding: 5px;">
      <p><strong>Copy formatting from one place to another</strong></p>
      <ul style="margin: 5px 0; padding-left: 20px;">
        <li>Single-click: Apply once</li>
        <li>Double-click: Apply multiple times</li>
        <li>Press ESC to cancel</li>
      </ul>
      <p style="margin-top: 5px;"><em>Keyboard: Ctrl+Shift+C, then Ctrl+Shift+V</em></p>
    </div>
  `,
  cssClass: 'advanced-tooltip'
};

<RibbonItemDirective 
  type="Button" 
  ribbonTooltipSettings={advancedTooltip}
  buttonSettings={{ 
    iconCss: "e-icons e-format-painter", 
    content: "Format Painter" 
  }}>
</RibbonItemDirective>

Item Template for Custom Items

Define custom templates for ribbon items beyond the built-in Template type:

import { RibbonItemDirective } from "@syncfusion/ej2-react-ribbon";

// Custom item template that receives activeSize as context
<RibbonItemDirective 
  type="Button" 
  itemTemplate={(props: any) => {
    const size = props.activeSize || 'Medium';
    return (
      <div className={`custom-item size-${size.toLowerCase()}`}>
        <span className="e-icons e-custom-icon"></span>
        {size !== 'Small' && <span className="item-text">Custom Action</span>}
      </div>
    );
  }}
  buttonSettings={{ content: "Custom" }}>
</RibbonItemDirective>

itemTemplate Property:

• Type: string | function | JSX.Element | HTMLElement
• Context: Receives activeSize property as string in template context
• Purpose: Complete control over item rendering

Responsive Template Example:

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective } from "@syncfusion/ej2-react-ribbon";

function App() {
  const customItemTemplate = (props: any) => {
    const activeSize = props.activeSize || 'Medium';
    
    // Different rendering based on size
    if (activeSize === 'Large') {
      return (
        <div style={{ 
          display: 'flex', 
          flexDirection: 'column', 
          alignItems: 'center', 
          padding: '8px',
          cursor: 'pointer'
        }}>
          <span className="e-icons e-star" style={{ fontSize: '24px', color: '#ffc107' }}></span>
          <span style={{ marginTop: '4px', fontSize: '12px' }}>Favorite</span>
        </div>
      );
    } else if (activeSize === 'Medium') {
      return (
        <div style={{ 
          display: 'flex', 
          alignItems: 'center', 
          padding: '6px',
          cursor: 'pointer'
        }}>
          <span className="e-icons e-star" style={{ fontSize: '16px', color: '#ffc107', marginRight: '6px' }}></span>
          <span style={{ fontSize: '12px' }}>Favorite</span>
        </div>
      );
    } else {
      return (
        <div style={{ padding: '6px', cursor: 'pointer' }}>
          <span className="e-icons e-star" style={{ fontSize: '16px', color: '#ffc107' }}></span>
        </div>
      );
    }
  };

  return (
    <RibbonComponent id="ribbon">
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Actions">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective 
                      type="Template" 
                      itemTemplate={customItemTemplate}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

export default App;

Template with State Management:

import { useState } from 'react';

function App() {
  const [isFavorite, setIsFavorite] = useState(false);

  const favoriteTemplate = (props: any) => {
    const handleClick = () => {
      setIsFavorite(!isFavorite);
    };

    return (
      <button 
        onClick={handleClick}
        style={{
          background: 'transparent',
          border: 'none',
          cursor: 'pointer',
          padding: '8px'
        }}>
        <span 
          className="e-icons e-star" 
          style={{ 
            fontSize: '20px', 
            color: isFavorite ? '#ffc107' : '#ccc' 
          }}>
        </span>
      </button>
    );
  };

  return (
    <RibbonComponent id="ribbon">
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Quick Actions">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective 
                      type="Template" 
                      itemTemplate={favoriteTemplate}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

Use Cases:

• Custom controls not provided by built-in types
• Dynamic content based on application state
• Size-aware rendering
• Interactive components with complex logic

Enable or Disable Items

// Disable specific item
<RibbonItemDirective type="Button" 
  disabled={true}
  buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
</RibbonItemDirective>

// Disable CheckBox
<RibbonItemDirective type="CheckBox" 
  disabled={true}
  checkBoxSettings={{ label: "Ruler", checked: true }}>
</RibbonItemDirective>

// Disable DropDown
<RibbonItemDirective type="DropDown" 
  disabled={true}
  dropDownSettings={{ content: "Table", iconCss: "e-icons e-table" }}>
</RibbonItemDirective>

Group Configuration

Group-level properties:

<RibbonGroupDirective 
  header="Clipboard" 
  id="clipboardGroup"
  groupIconCss="e-icons e-paste"
  showLauncherIcon={true}
  isCollapsible={true}
  priority={2}
  enableGroupOverflow={false}>
  {/* Collections and items */}
</RibbonGroupDirective>

Group Properties:

• header - Group title text
• id - Unique identifier
• groupIconCss - Icon for overflow button
• showLauncherIcon - Show launcher icon (boolean)
• isCollapsible - Allow group to collapse (default: true)
• priority - Collapse order (higher = collapse first)
• enableGroupOverflow - Dedicated overflow for group (boolean)

Group Orientation

Arrange items vertically or horizontally:

// Column orientation (default)
<RibbonGroupDirective header="Clipboard" orientation="Column">
  {/* Items stack vertically */}
</RibbonGroupDirective>

// Row orientation
<RibbonGroupDirective header="Font" orientation="Row">
  {/* Items arrange horizontally */}
</RibbonGroupDirective>

Constraints:

• Column: Multiple items per collection, up to 3 small/medium-sized items
• Row: Maximum 3 collections per group, each with any number of items

Common Patterns

Pattern 1: Large Primary + Small Secondary Large paste button with small cut/copy buttons

Pattern 2: ComboBox + Action Buttons Font selector with formatting buttons

Pattern 3: Grouped Format Buttons GroupButton for alignment (Left, Center, Right, Justify)

Layouts and Display Modes

Table of Contents

• Layout Overview
• Classic Layout
• Simplified Layout
• Layout Switching
• Display Options
• Item Sizing in Layouts
• Responsive Behavior
• Minimized State
• Hide Layout Switcher

Layout Overview

The Ribbon supports two layouts:

Classic Layout

The default layout that organizes items and groups in traditional multi-row format:

import { RibbonComponent, RibbonTabsDirective, RibbonTabDirective, RibbonGroupsDirective, RibbonGroupDirective, RibbonCollectionsDirective, RibbonCollectionDirective, RibbonItemsDirective, RibbonItemDirective, RibbonItemSize } from "@syncfusion/ej2-react-ribbon";
import { ItemModel } from "@syncfusion/ej2-splitbuttons";

function App() {
  const pasteOptions: ItemModel[] = [
    { text: "Keep Source Format" },
    { text: "Merge format" },
    { text: "Keep text only" }
  ];

  return (
    <RibbonComponent id="ribbon">
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Clipboard">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective type="SplitButton" allowedSizes={RibbonItemSize.Large}
                      splitButtonSettings={{ iconCss: "e-icons e-paste", items: pasteOptions, content: "Paste" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-copy", content: "Copy" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

export default App;

Explicit Selection:

<RibbonComponent id="ribbon">
  {/* Classic is default, but can be explicit */}
  {/* activeLayout property is optional for Classic */}
</RibbonComponent>

Simplified Layout

Compact single-row layout for constrained spaces:

import { ItemModel } from "@syncfusion/ej2-splitbuttons";

function App() {
  const pasteOptions: ItemModel[] = [
    { text: "Keep Source Format" },
    { text: "Merge format" },
    { text: "Keep text only" }
  ];

  return (
    <RibbonComponent id="ribbon" activeLayout='Simplified'>
      <RibbonTabsDirective>
        <RibbonTabDirective header="Home">
          <RibbonGroupsDirective>
            <RibbonGroupDirective header="Clipboard">
              <RibbonCollectionsDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective type="SplitButton"
                      splitButtonSettings={{ iconCss: "e-icons e-paste", items: pasteOptions, content: "Paste" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
                <RibbonCollectionDirective>
                  <RibbonItemsDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
                    </RibbonItemDirective>
                    <RibbonItemDirective type="Button" buttonSettings={{ iconCss: "e-icons e-copy", content: "Copy" }}>
                    </RibbonItemDirective>
                  </RibbonItemsDirective>
                </RibbonCollectionDirective>
              </RibbonCollectionsDirective>
            </RibbonGroupDirective>
          </RibbonGroupsDirective>
        </RibbonTabDirective>
      </RibbonTabsDirective>
    </RibbonComponent>
  );
}

export default App;

Simplified Layout Characteristics:

• Single row of items
• GroupButton items render as dropdowns
• More compact display
• Ideal for mobile and responsive designs

Layout Switching

Users can switch layouts via the layout switcher button in the ribbon header.

Enable/Disable Layout Switcher:

// Hide layout switcher (users cannot switch)
<RibbonComponent id="ribbon" hideLayoutSwitcher={true}>
  {/* Tabs and groups */}
</RibbonComponent>

// Show layout switcher (default)
<RibbonComponent id="ribbon" hideLayoutSwitcher={false}>
  {/* Tabs and groups */}
</RibbonComponent>

Display Options

Control which layouts each item appears in:

import { DisplayMode } from "@syncfusion/ej2-react-ribbon";

// Display only in Classic layout
<RibbonItemDirective type="Button" 
  displayOptions={DisplayMode.Classic}
  buttonSettings={{ iconCss: "e-icons e-cut", content: "Cut" }}>
</RibbonItemDirective>

// Display only in Simplified layout
<RibbonItemDirective type="Button" 
  displayOptions={DisplayMode.Simplified}
  buttonSettings={{ iconCss: "e-icons e-copy", content: "Copy" }}>
</RibbonItemDirective>

// Display only in overflow popup
<RibbonItemDirective type="Button" 
  displayOptions={DisplayMode.Overflow}
  buttonSettings={{ iconCss: "e-icons e-paste", content: "Paste" }}>
</RibbonItemDirective>

// Display in all layouts (default)
<RibbonItemDirective type="Button" 
  displayOptions={DisplayMode.Auto}
  buttonSettings={{ iconCss: "e-icons e-bold", content: "Bold" }}>
</RibbonItemDirective>

Display Mode Options:

• DisplayMode.Auto - Appear in all layouts
• DisplayMode.Classic - Classic layout only
• DisplayMode.Simplified - Simplified layout only
• DisplayMode.Overflow - Overflow popup only

Item Sizing in Layouts

Item sizes adjust automatically based on available space:

import { RibbonItemSize } from "@syncfusion/ej2-react-ribbon";

// Large size (large icon + text)
<RibbonItemDirective type="SplitButton" 
  allowedSizes={RibbonItemSize.Large}
  splitButtonSettings={{ content: "Paste" }}>
</RibbonItemDirective>

// Medium size (small icon + text)
<RibbonItemDirective type="Button" 
  allowedSizes={RibbonItemSize.Medium}
  buttonSettings={{ content: "Copy" }}>
</RibbonItemDirective>

// Small size (icon only)
<RibbonItemDirective type="Button" 
  allowedSizes={RibbonItemSize.Small}
  buttonSettings={{ content: "Cut" }}>
</RibbonItemDirective>

Automatic Size Transition:

During ribbon resizing: 1. Items start at their maximum allowed size (Large) 2. As space decreases: Large → Medium → Small 3. Items that don't fit move to overflow

Responsive Behavior

Handle responsive ribbon resizing with group configuration:

// Non-collapsible groups stay visible
<RibbonGroupDirective header="Font" isCollapsible={false}>
  {/* Always visible */}
</RibbonGroupDirective>

// Collapsible groups collapse when space is limited
<RibbonGroupDirective header="Clipboard" isCollapsible={true} priority={1}>
  {/* Collapses when needed */}
</RibbonGroupDirective>

// Set priority for collapse order
<RibbonGroupDirective header="Editor" priority={2}>
  {/* Collapses first */}
</RibbonGroupDirective>

Minimized State

Collapse the ribbon to show only tab headers, saving vertical space:

// Default (minimized=false)
<RibbonComponent id="ribbon">
  {/* Ribbon expanded */}
</RibbonComponent>

// Start minimized
<RibbonComponent id="ribbon" isMinimized='true'>
  {/* Ribbon collapsed initially */}
</RibbonComponent>

// Toggle minimized state programmatically
import { useRef } from 'react';

function App() {
  let ribbonObj = useRef<RibbonComponent>(null);

  const toggleMinimized = () => {
    if (ribbonObj.current) {
      ribbonObj.current.isMinimized = !ribbonObj.current.isMinimized;
    }
  };

  return (
    <div>
      <button onClick={toggleMinimized}>Toggle Minimize</button>
      <RibbonComponent id="ribbon" ref={ribbonObj}>
        {/* Tabs and groups */}
      </RibbonComponent>
    </div>
  );
}

Minimized Behavior:

• Double-click tab header to minimize/expand
• Click collapse/expand icon in ribbon header
• Clicking a tab header temporarily shows content
• Content hides when clicking elsewhere

Hide Layout Switcher

Hide the layout switcher button if switching isn't needed:

import { useRef } from 'react';
import { CheckBoxComponent } from '@syncfusion/ej2-react-buttons';

function App() {
  let ribbonObj = useRef<RibbonComponent>(null);

  const onChange = (args) => {
    if (ribbonObj.current) {
      ribbonObj.current.hideLayoutSwitcher = !args.checked;
    }
  };

  return (
    <div>
      <CheckBoxComponent label="Show/Hide Layout Switcher" checked={true} change={onChange}></CheckBoxComponent>
      <RibbonComponent id="ribbon" ref={ribbonObj} hideLayoutSwitcher={false}>
        {/* Tabs and groups */}
      </RibbonComponent>
    </div>
  );
}

Complete Responsive Example

<RibbonComponent id="ribbon" activeLayout='Classic' hideLayoutSwitcher={false}>
  <RibbonTabsDirective>
    <RibbonTabDirective header="Home">
      <RibbonGroupsDirective>
        {/* High priority - collapses last */}
        <RibbonGroupDirective header="Clipboard" priority={0} isCollapsible={false}>
          {/* Items */}
        </RibbonGroupDirective>

        {/* Medium priority */}
        <RibbonGroupDirective header="Font" priority={1}>
          {/* Items */}
        </RibbonGroupDirective>

        {/* Low priority - collapses first */}
        <RibbonGroupDirective header="Styles" priority={2}>
          {/* Items with Simplified display */}
          <RibbonItemDirective type="Button" 
            displayOptions={DisplayMode.Simplified}
            buttonSettings={{ content: "Style" }}>
          </RibbonItemDirective>
        </RibbonGroupDirective>
      </RibbonGroupsDirective>
    </RibbonTabDirective>
  </RibbonTabsDirective>
</RibbonComponent>

Best Practices

1. Layout Switcher: Provide layout switcher for desktop applications 2. Display Options: Use for layout-specific items 3. Non-Collapsible Groups: Keep essential groups visible 4. Size Consistency: Set appropriate allowedSizes for all items 5. Priority Planning: Set group priority based on importance 6. Mobile Considerations: Use Simplified layout on mobile devices