syncfusion-angular-ribbon

# Syncfusion Angular Ribbon Component ## Component Overview The **Syncfusion Angular Ribbon** is a professional command interface component that organizes application commands in a tabbed ribbon format, similar to Microsoft Office. It features: - **Hierarchical Command Organization:** Tabs → Groups → Collections → Items for logical command structure - **7 Built-in Item Types:** Button, CheckBox, DropDown, SplitButton, ComboBox, ColorPicker, GroupButton, and Gallery - **Dual Layout Modes:** Classic (multi-row) and Simplified (collapsible) layouts with automatic resizing - **File Menu & Backstage Views:** Traditional file menus or modern backstage interfaces for document operations - **Contextual Tabs:** Dynamic tabs that appear based on user selection or context - **Responsive Resizing:** Automatic item size adjustment (Large, Medium, Small) based on available width - **Keyboard Navigation:** Full keytips support for keyboard-first workflows - **Accessibility Features:** WCAG compliance with ARIA attributes and screen reader support - **RTL Support:** Right-to-left layout for Arabic, Hebrew, Persian, and Urdu languages - **Gallery Items:** Visual selection panels for themes, styles, and color schemes - **Help Pane:** Customizable help pane with template support - **Advanced Event System:** Comprehensive events for tab selection, collapse/expand, launcher clicks, and item interactions - **Highly Configurable:** Extensive API with 20+ ribbon properties, 30+ item properties, and 10+ events ## Key Concepts & Hierarchy **Important concepts:** - **Tabs:** Organize major feature categories (Home, Insert, View) - **Groups:** Group related commands within a tab (Clipboard, Font, Alignment) - **Collections:** Visual groupings within a group for better organization - **Items:** Individual commands with 7 types (Button, DropDown, ColorPicker, etc.) - **Layouts:** Classic (multi-row) or Simplified (collapse-capable) with automatic switching - **File Menu/Backstage:** Application-level operations (New, Open, Save, Print) ## Documentation and Navigation Guide ### Getting Started 📄 **Read:** [references/getting-started.md](references/getting-started.md) - Installation and package setup (Ivy vs ngcc) - CSS theme imports and dependencies - Creating your first Ribbon - Adding tabs and groups - Basic items and running the application ### Tabs, Groups, and Items Structure 📄 **Read:** [references/tabs-groups-items.md](references/tabs-groups-items.md) - Tab hierarchy and properties - Adding groups to tabs - Ribbon collections and items - Item size configuration (Large, Medium, Small) - Orientation settings (Row/Column) - Multiple tabs and groups examples ### Item Types and Configuration 📄 **Read:** [references/item-types.md](references/item-types.md) - All 7 built-in item types - Button items (toggle, disabled states) - CheckBox, DropDown, SplitButton items - ComboBox, ColorPicker, GroupButton items - Complete code examples for each type - Item settings models and properties ### Ribbon Layouts and Resizing 📄 **Read:** [references/layouts.md](references/layouts.md) - Classic layout (default multi-row format) - Simplified layout (with collapse support) - Switching between layouts - Item size allowances and configuration - Responsive resizing behavior - Layout examples and best practices ### File Menu and Backstage Views 📄 **Read:** [references/file-menu-and-backstage.md](references/file-menu-and-backstage.md) - File Menu configuration and visibility - Adding menu items with icons and actions - Backstage view as file menu replacement - Backstage items and content - Footer items and separators - Back button customization - Target element positioning - Complete file menu and backstage examples ### Advanced Features 📄 **Read:** [references/advanced-features.md](references/advanced-features.md) - Contextual tabs (dynamic tab creation) - Keytips for keyboard navigation - Gallery items for visual selection - Help pane templates - Tooltip configuration - Resizing behavior and responsive design - RTL support for right-to-left languages - Accessibility features and WCAG compliance ### Events and Interactivity 📄 **Read:** [references/events.md](references/events.md) - Tab selection events (tabSelected, tabSelecting) - Ribbon collapse/expand events - Backstage item click events - Event arguments and cancellation - Event handling patterns - Complete event examples ### Customization and Styling 📄 **Read:** [references/customization-and-styling.md](references/customization-and-styling.md) - CSS class customization - Theme integration and switching - CSS variables for styling - Custom styling examples - Group icon customization - Item customization and appearance - Launcher icon usage ## Quick Start Example Here's a minimal Ribbon with Home and Insert tabs: ```typescript import { Component } from "@angular/core"; import { RibbonModule } from '@syncfusion/ej2-angular-ribbon'; import { RibbonButtonSettingsModel, RibbonSplitButtonSettingsModel } from '@syncfusion/ej2-angular-ribbon'; @Component({ imports: [ RibbonModule ], standalone: true, selector: "app-root", template: ` <ejs-ribbon id="ribbon"> <e-ribbon-tabs> <e-ribbon-tab header="Home"> <e-ribbon-groups> <e-ribbon-group header="Clipboard" orientation="Row"> <e-ribbon-collections> <e-ribbon-collection> <e-ribbon-items> <e-ribbon-item type="SplitButton" [splitButtonSettings]="pasteSettings"></e-ribbon-item> </e-ribbon-items> </e-ribbon-collection> <e-ribbon-collection> <e-ribbon-items> <e-ribbon-item type="Button" [buttonSettings]="cutButton"></e-ribbon-item> <e-ribbon-item type="Button" [buttonSettings]="copyButton"></e-ribbon-item> </e-ribbon-items> </e-ribbon-collection> </e-ribbon-collections> </e-ribbon-group> </e-ribbon-groups> </e-ribbon-tab> <e-ribbon-tab header="Insert"> <e-ribbon-groups> <e-ribbon-group header="Illustrations" orientation="Row"> <e-ribbon-collections> <e-ribbon-collection> <e-ribbon-items> <e-ribbon-item type="Button" [buttonSettings]="chartButton"></e-ribbon-item> </e-ribbon-items> </e-ribbon-collection> </e-ribbon-collections> </e-ribbon-group> </e-ribbon-groups> </e-ribbon-tab> </e-ribbon-tabs> </ejs-ribbon> `, styleUrls: ['./app.component.css'] }) export class AppComponent { public pasteSettings = { iconCss: "e-icons e-paste", items: [{ text: "Keep Source Format" }, { text: "Merge format" }], content: "Paste" }; public cutButton: RibbonButtonSettingsModel = { iconCss: "e-icons e-cut", content: "Cut" }; public copyButton: RibbonButtonSettingsModel = { iconCss: "e-icons e-copy", content: "Copy" }; public chartButton: RibbonButtonSettingsModel = { iconCss: "e-icons e-chart", content: "Chart" }; } ``` --- ## Common Patterns ### Pattern 1: Multi-Tab Command Interface 1. Define multiple tabs for major features (Home, Insert, View, Format) 2. Add groups within each tab for related commands 3. Configure collections to organize items visually 4. Use appropriate item types (Button, DropDown, ColorPicker) 5. Set `activeLayout` to Classic or Simplified 6. Handle `tabSelected` event for tab-specific actions ### Pattern 2: File Menu Integration with Backstage 1. Configure `fileMenu` or `backStageMenu` for document operations 2. Add menu items for New, Open, Save, Print, Export 3. Set icons with `iconCss` and content areas for backstage 4. Handle menu item clicks with event handlers 5. Use footer items for settings or account options 6. Configure back button for backstage navigation ### Pattern 3: Responsive Resizing with Size Priorities 1. Set `allowedSizes` array on items (Large, Medium, Small) 2. Configure `activeSize` for initial display size 3. Ribbon automatically adjusts item sizes based on width 4. Use `Large` for primary commands, `Small` for secondary 5. Handle `ribbonCollapsing` event for custom resize logic 6. Test responsive behavior at different viewport widths ### Pattern 4: Contextual Tabs for Dynamic Commands 1. Define `contextualTabs` array with tab configurations 2. Set `visible` property based on user selection or context 3. Use `isSelected` to activate contextual tab programmatically 4. Add tab-specific groups and items for contextual commands 5. Handle `tabSelected` to detect contextual tab activation 6. Toggle visibility dynamically in response to user actions ### Pattern 5: Keyboard Navigation with Keytips 1. Enable `enableKeyTips` on ribbon component 2. Assign `keyTip` property to tabs (Alt+H for Home) 3. Add keytips to groups and individual items 4. Configure `layoutSwitcherKeyTip` for layout toggle 5. Set keytips on file menu and backstage items 6. Follow consistent keytip patterns (Alt+ letter combinations) ### Pattern 6: Gallery Items for Visual Selection 1. Configure items with `type="Gallery"` for visual panels 2. Define `gallerySettings` with groups and items 3. Set `itemCount`, `popupWidth`, `popupHeight` for display 4. Use templates for custom gallery item rendering 5. Handle selection events for gallery item clicks 6. Common use cases: themes, styles, colors, table designs --- ## Key Properties & Events ### Core Ribbon Configuration | Property | Type | Default | When to Use | |----------|------|---------|------------| | `tabs` | RibbonTabModel[] | `[]` | Define ribbon tabs with groups and items | | `activeLayout` | LayoutType | `'Classic'` | Set layout mode (Classic or Simplified) | | `selectedTab` | number | `0` | Set or get the currently active tab index | | `isMinimized` | boolean | `false` | Control ribbon minimized state | ### Layout & Appearance | Property | Type | Default | When to Use | |----------|------|---------|------------| | `width` | string \| number | `'100%'` | Set ribbon container width | | `cssClass` | string | `''` | Apply custom CSS classes for styling and themes | | `hideLayoutSwitcher` | boolean | `false` | Hide the Classic/Simplified layout toggle button | | `tabAnimation` | object | `null` | Configure tab switching animation settings | ### Keyboard & Accessibility | Property | Type | Default | When to Use | |----------|------|---------|------------| | `enableKeyTips` | boolean | `false` | Enable keytips for keyboard navigation (Alt+ shortcuts) | | `layoutSwitcherKeyTip` | string | `''` | Set keytip for layout switcher button | | `launcherIconCss` | string | `''` | Default CSS class for launcher icons across all groups | ### File Menu & Backstage | Property | Type | Default | When to Use | |----------|------|---------|------------| | `fileMenu` | FileMenuSettingsModel | `null` | Configure traditional file menu (New, Open, Save, Print) | | `backStageMenu` | BackStageMenuModel | `null` | Configure modern backstage view (replaces file menu) | ### Advanced Features | Property | Type | Default | When to Use | |----------|------|---------|------------| | `contextualTabs` | RibbonContextualTabModel[] | `[]` | Define tabs that appear based on context or selection | | `helpPaneTemplate` | string | `''` | Custom template for help pane content | ### Globalization | Property | Type | Default | When to Use | |----------|------|---------|------------| | `locale` | string | `'en-US'` | Set language/culture for localization | | `enableRtl` | boolean | `false` | Enable right-to-left layout (Arabic, Hebrew, Persian, Urdu) | | `enablePersistence` | boolean | `false` | Save ribbon state between page reloads | ### Tab Configuration | Property | Type | Default | When to Use | |----------|------|---------|------------| | `header` | string | `''` | Tab display text (Home, Insert, View) | | `groups` | RibbonGroupModel[] | `[]` | Array of groups within the tab | | `id` | string | `''` | Unique identifier for the tab | | `keyTip` | string | `''` | Keyboard shortcut keytip (H for Home) | ### Group Configuration | Property | Type | Default | When to Use | |----------|------|---------|------------| | `header` | string | `''` | Group display text (Clipboard, Font, Alignment) | | `orientation` | ItemOrientation | `'Column'` | Layout direction (Row or Column) | | `enableGroupOverflow` | boolean | `false` | Show overflow dropdown when group doesn't fit | | `isCollapsible` | boolean | `true` | Allow group to collapse in simplified layout | | `showLauncherIcon` | boolean | `false` | Show launcher icon for dialog/pane launch | | `groupIconCss` | string | `''` | CSS class for group icon in overflow/launcher | ### Item Configuration | Property | Type | Default | When to Use |