Getting Started with Ribbon Web Component
Smart UI Web Components work with current evergreen browsers and Node 18+ for local tooling; pin package versions to match your project policy.
Smart UI is distributed as the smart-webcomponents NPM package. You can also use the full download from the Download page.
Quick start
- Install the package:
npm install smart-webcomponents
- Load the Ribbon module (ES module script):
<script type="module" src="node_modules/smart-webcomponents/source/modules/smart.ribbon.js"></script>
- Add the default stylesheet (prefer angular.json / bundler entry in app codebases; for plain HTML use a link):
<link rel="stylesheet" type="text/css" href="node_modules/smart-webcomponents/source/styles/smart.default.css" />
- Add markup in one of two ways - semantic custom element (the component tag is in your HTML) or a host
div(you mount programmatically with appendTo):
Semantic element (id matches the selector in Smart()):
<smart-ribbon id="ribbon"></smart-ribbon>
Host container (id matches appendTo on Smart.Ribbon):
<div id="ribbonContainer"></div>
- Initialize after the module loads: define a const ribbonOptions object, then either bind with Smart('#ribbon', ...) on the semantic tag or use new Smart.Ribbon({ ...ribbonOptions, appendTo: '#ribbonContainer' }) on the host
div:
<script type="module"> import 'node_modules/smart-webcomponents/source/modules/smart.ribbon.js'; const ribbonOptions = { dataSource: [{ label: 'Home', ribbonGroups: [{ label: 'Clipboard', icon: 'content_paste material-icons', ribbonItems: [{ label: 'Paste', icon: 'content_paste material-icons', size: 'normal', cssClass: 'flat', type: 'button', allowedSizes: ['normal'] }, { type: 'group', direction: 'vertical', ribbonItems: [{ label: 'Cut', icon: 'content_cut material-icons', type: 'button', cssClass: 'flat', size: 'verySmall', }, { label: 'Copy', icon: 'content_copy material-icons', type: 'button', cssClass: 'flat', size: 'verySmall' } ] } ] }, { label: 'Font', icon: 'format_bold material-icons', ribbonItems: [{ type: 'group', direction: 'vertical', ribbonItems: [{ type: 'group', direction: 'horizontal', ribbonItems: [{ label: 'Font', type: 'input', settings: { dataSource: ['Arial', 'Arial Black', 'Calibri'], value: 'Arial', dropDownButtonPosition: 'right' }, cssClass: 'font-family-input' }, { label: 'Font size', type: 'input', settings: { dataSource: [8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, 36, 48, 72], value: '11', dropDownButtonPosition: 'right' }, cssClass: 'font-size-input' }, ] }, { type: 'group', direction: 'horizontal', ribbonItems: [{ label: 'Bold', icon: 'format_bold material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { label: 'Italic', icon: 'format_italic material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { label: 'Underline', icon: 'format_underlined material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { type: 'separator' }, { label: '', tooltip: 'Font color', itemTemplate: '', settings: { value: '#000000', valueDisplayMode: 'colorBox', dropDownAppendTo: 'body', }, } ] } ] }] }, { label: 'Paragraph', icon: 'format_align_left material-icons', ribbonItems: [{ type: 'group', direction: 'vertical', ribbonItems: [{ type: 'group', direction: 'horizontal', ribbonItems: [{ label: 'Align left', icon: 'format_align_left material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { label: 'Align center', icon: 'format_align_center material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { label: 'Align right', icon: 'format_align_right material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { type: 'separator' }, { label: 'Justify', icon: 'format_align_justify material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' } ] }, { type: 'group', direction: 'horizontal', ribbonItems: [{ label: 'Numbered list', icon: 'format_list_numbered material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { label: 'Bulleted list', icon: 'format_list_bulleted material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { type: 'separator' }, { label: 'Decrease indent', icon: 'format_indent_decrease material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { label: 'Increase indent', icon: 'format_indent_increase material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' } ] } ] }, { type: 'separator' }, { type: 'group', direction: 'vertical', ribbonItems: [{ label: 'Wrap text', icon: 'wrap_text material-icons', type: 'button', cssClass: 'flat', size: 'verySmall', allowedSizes: ['iconOnly','verySmall'] }, { label: 'Sort Selection', icon: 'sort_by_alpha material-icons', type: 'button', cssClass: 'flat', size: 'verySmall', allowedSizes: ['iconOnly','verySmall'] } ] } ] }, { label: 'Editing', icon: 'edit material-icons', ribbonItems: [{ type: 'group', wrapSize: 'verySmall', ribbonItems: [{ label: 'Find', icon: 'search material-icons', type: 'button', cssClass: 'flat', size: 'normal', allowedSizes: ['verySmall', 'normal'] }, { type: 'group', wrapSize: 'small', ribbonItems: [ { label: 'Replace', icon: 'find_replace material-icons', type: 'button', cssClass: 'flat', size: 'normal', allowedSizes: ['verySmall', 'small', 'normal'] }, { label: 'Select all', icon: 'select_all material-icons', type: 'button', cssClass: 'flat', size: 'normal', allowedSizes: ['verySmall', 'small', 'normal'] } ] }, ] }] } ] }, { label: 'Insert', ribbonGroups: [{ label: 'Tables', icon: 'table_chart material-icons', ribbonItems: [{ type: 'group', direction: 'vertical', ribbonItems: [{ type: 'group', direction: 'horizontal', ribbonItems: [{ label: 'Insert table', icon: 'table_chart material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { label: 'Insert row above', icon: 'keyboard_arrow_up material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { label: 'Insert row below', icon: 'keyboard_arrow_down material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { label: 'Insert column left', icon: 'keyboard_arrow_left material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { label: 'Insert column right', icon: 'keyboard_arrow_right material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { type: 'separator' }, { label: 'Delete row', icon: 'delete_sweep material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { label: 'Delete column', icon: 'delete_sweep material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' }, { label: 'Delete table', icon: 'delete_sweep material-icons', type: 'button', cssClass: 'flat', size: 'iconOnly' } ] }, { label: 'Table styles', itemTemplate: ' ', settings: { dataSource: ['Table style 1', 'Table style 2', 'Table style 3', 'Table style 4', 'Table style 5'], selectedValues: ['Table style 1'], dropDownAppendTo: 'body', }, cssClass: 'table-styles-drop-down' } ] }] }, { label: 'Illustrations', icon: 'insert_photo material-icons', ribbonItems: [{ type: 'group', direction: 'vertical', ribbonItems: [{ label: 'Pictures', icon: 'insert_photo material-icons', type: 'button', cssClass: 'flat', size: 'verySmall', allowedSizes: ['verySmall'] }, { label: 'Online pictures', icon: 'cloud_upload material-icons', type: 'button', cssClass: 'flat', size: 'verySmall', allowedSizes: ['verySmall'] }, { label: 'Shapes', icon: 'bubble_chart material-icons', type: 'button', cssClass: 'flat', size: 'verySmall', allowedSizes: ['verySmall'] }, ] }, { type: 'separator' }, { type: 'group', wrapSize: 'small', ribbonItems: [ { label: 'Icons', icon: 'insert_emoticon material-icons', type: 'button', cssClass: 'flat', size: 'normal', allowedSizes: ['small','normal'] }, { label: '3D models', icon: 'aspect_ratio material-icons', type: 'button', cssClass: 'flat', size: 'normal', allowedSizes: ['small','normal'] }] } ] } ] }, { label: 'View', ribbonGroups: [{ label: 'Show', icon: 'visibility material-icons', wrapSize: 'small', ribbonItems: [{ label: 'Gridlines', icon: 'grid_on material-icons', type: 'button', cssClass: 'flat', size: 'normal', allowedSizes: ['small','normal'] }, { label: 'Headings', icon: 'view_headline material-icons', type: 'button', cssClass: 'flat', size: 'normal', allowedSizes: ['small','normal'] } ] }, { label: 'Zoom', icon: 'zoom_out_map material-icons', wrapSize: 'small', ribbonItems: [{ label: 'Zoom to page', icon: 'pageview material-icons', type: 'button', cssClass: 'flat', size: 'normal', allowedSizes: ['small','normal'] }, { label: 'Zoom to selection', icon: 'zoom_out_map material-icons', type: 'button', cssClass: 'flat', size: 'normal', allowedSizes: ['small','normal'] }, ] } ] }, { label: 'Help', wrapSize: 'small', ribbonGroups: [{ label: 'Help', icon: 'help_outline material-icons', ribbonItems: [{ label: 'Help', icon: 'help_outline material-icons', type: 'button', cssClass: 'flat', size: 'normal', allowedSizes: ['verySmall','small','normal'] }, { label: 'About', icon: 'info_outline material-icons', type: 'button', cssClass: 'flat', size: 'normal', allowedSizes: ['verySmall','small','normal'] } ] }] } ], fileMenu: { type: 'dropDown', items: [{ label: 'New', shortcut: 'Ctrl+N' }, { label: 'Open', shortcut: 'Ctrl+0' }, { label: 'Open Containing Folder', items: [{ label: 'Explorer' }, { label: 'cmd' } ] }, { label: 'Save', shortcut: 'Ctrl+S', disabled: true, separator: true }, { label: 'Exit', shortcut: 'Alt+F4' } ] } } } }; // Option A - semantic <smart-ribbon> with id="ribbon" Smart('#ribbon', class { get properties() { return ribbonOptions; } }); // Option B - host div id="ribbonContainer" // const ribbonInstance = new Smart.Ribbon({ // ...ribbonOptions, // appendTo: '#ribbonContainer' // }); // Option C - constructor(selector, options), then append the returned element yourself // const myRibbon = new Smart.Ribbon('#ribbon', ribbonOptions); // document.body.appendChild(myRibbon); </script>
Uncomment Option B when you use the host
div; use Option A when you use the semantic element. The Runtime cookbook also documents new Smart.Ribbon('#ribbon', ribbonOptions) with appendChild, and document.createElement('smart-ribbon') with .props or Object.assign (all are valid patterns; do not combine overlapping patterns for the same instance unless you intend multiple components). - Serve the folder over HTTP (or use your bundler dev server) and open the page.
Runtime cookbook
Alternative creation patterns and imperative APIs. These are all valid ways to create Smart UI components: semantic markup + Smart(); new Smart.Ribbon({ ...options, appendTo: '#...' }); new Smart.Ribbon('#ribbon', ribbonOptions) plus appendChild on the returned element; and document.createElement('smart-ribbon') then assigning options via .props or Object.assign on the element.
Constructor with a selector string and options, then append the returned element (for example const myRibbon = new Smart.Ribbon('#ribbon', ribbonOptions)):
const ribbonOptions = {
dataSource: [{
label: 'Home',
ribbonGroups: [{
label: 'Clipboard',
icon: 'content_paste material-icons',
ribbonItems: [{
label: 'Paste',
icon: 'content_paste material-icons',
size: 'normal',
cssClass: 'flat',
type: 'button',
allowedSizes: ['normal']
},
{
type: 'group',
direction: 'vertical',
ribbonItems: [{
label: 'Cut',
icon: 'content_cut material-icons',
type: 'button',
cssClass: 'flat',
size: 'verySmall',
},
{
label: 'Copy',
icon: 'content_copy material-icons',
type: 'button',
cssClass: 'flat',
size: 'verySmall'
}
]
}
]
},
{
label: 'Font',
icon: 'format_bold material-icons',
ribbonItems: [{
type: 'group',
direction: 'vertical',
ribbonItems: [{
type: 'group',
direction: 'horizontal',
ribbonItems: [{
label: 'Font',
type: 'input',
settings: {
dataSource: ['Arial', 'Arial Black', 'Calibri'],
value: 'Arial',
dropDownButtonPosition: 'right'
},
cssClass: 'font-family-input'
},
{
label: 'Font size',
type: 'input',
settings: {
dataSource: [8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, 36, 48, 72],
value: '11',
dropDownButtonPosition: 'right'
},
cssClass: 'font-size-input'
},
]
},
{
type: 'group',
direction: 'horizontal',
ribbonItems: [{
label: 'Bold',
icon: 'format_bold material-icons',
type: 'button',
cssClass: 'flat',
size: 'iconOnly'
},
{
label: 'Italic',
icon: 'format_italic material-icons',
type: 'button',
cssClass: 'flat',
size: 'iconOnly'
},
{
label: 'Underline',
icon: 'format_underlined material-icons',
type: 'button',
cssClass: 'flat',
size: 'iconOnly'
},
{
type: 'separator'
},
{
label: '',
tooltip: 'Font color',
itemTemplate: '
Create with document.createElement('smart-ribbon'), assign properties (same as any custom element), then append:
const ribbonOptions = {
dataSource: [{
label: 'Home',
ribbonGroups: [{
label: 'Clipboard',
icon: 'content_paste material-icons',
ribbonItems: [{
label: 'Paste',
icon: 'content_paste material-icons',
size: 'normal',
cssClass: 'flat',
type: 'button',
allowedSizes: ['normal']
},
{
type: 'group',
direction: 'vertical',
ribbonItems: [{
label: 'Cut',
icon: 'content_cut material-icons',
type: 'button',
cssClass: 'flat',
size: 'verySmall',
},
{
label: 'Copy',
icon: 'content_copy material-icons',
type: 'button',
cssClass: 'flat',
size: 'verySmall'
}
]
}
]
},
{
label: 'Font',
icon: 'format_bold material-icons',
ribbonItems: [{
type: 'group',
direction: 'vertical',
ribbonItems: [{
type: 'group',
direction: 'horizontal',
ribbonItems: [{
label: 'Font',
type: 'input',
settings: {
dataSource: ['Arial', 'Arial Black', 'Calibri'],
value: 'Arial',
dropDownButtonPosition: 'right'
},
cssClass: 'font-family-input'
},
{
label: 'Font size',
type: 'input',
settings: {
dataSource: [8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, 36, 48, 72],
value: '11',
dropDownButtonPosition: 'right'
},
cssClass: 'font-size-input'
},
]
},
{
type: 'group',
direction: 'horizontal',
ribbonItems: [{
label: 'Bold',
icon: 'format_bold material-icons',
type: 'button',
cssClass: 'flat',
size: 'iconOnly'
},
{
label: 'Italic',
icon: 'format_italic material-icons',
type: 'button',
cssClass: 'flat',
size: 'iconOnly'
},
{
label: 'Underline',
icon: 'format_underlined material-icons',
type: 'button',
cssClass: 'flat',
size: 'iconOnly'
},
{
type: 'separator'
},
{
label: '',
tooltip: 'Font color',
itemTemplate: '
Host on a div with appendTo (import the module, then instantiate when the document is ready; the container id must match appendTo):
import "../../source/modules/smart.ribbon.js";
document.readyState === 'complete' ? init() : window.addEventListener('load', init);
function init() {
const ribbonOptions = {
dataSource: [{
label: 'Home',
ribbonGroups: [{
label: 'Clipboard',
icon: 'content_paste material-icons',
ribbonItems: [{
label: 'Paste',
icon: 'content_paste material-icons',
size: 'normal',
cssClass: 'flat',
type: 'button',
allowedSizes: ['normal']
},
{
type: 'group',
direction: 'vertical',
ribbonItems: [{
label: 'Cut',
icon: 'content_cut material-icons',
type: 'button',
cssClass: 'flat',
size: 'verySmall',
},
{
label: 'Copy',
icon: 'content_copy material-icons',
type: 'button',
cssClass: 'flat',
size: 'verySmall'
}
]
}
]
},
{
label: 'Font',
icon: 'format_bold material-icons',
ribbonItems: [{
type: 'group',
direction: 'vertical',
ribbonItems: [{
type: 'group',
direction: 'horizontal',
ribbonItems: [{
label: 'Font',
type: 'input',
settings: {
dataSource: ['Arial', 'Arial Black', 'Calibri'],
value: 'Arial',
dropDownButtonPosition: 'right'
},
cssClass: 'font-family-input'
},
{
label: 'Font size',
type: 'input',
settings: {
dataSource: [8, 9, 10, 11, 12, 14, 16, 18, 20, 22, 24, 28, 36, 48, 72],
value: '11',
dropDownButtonPosition: 'right'
},
cssClass: 'font-size-input'
},
]
},
{
type: 'group',
direction: 'horizontal',
ribbonItems: [{
label: 'Bold',
icon: 'format_bold material-icons',
type: 'button',
cssClass: 'flat',
size: 'iconOnly'
},
{
label: 'Italic',
icon: 'format_italic material-icons',
type: 'button',
cssClass: 'flat',
size: 'iconOnly'
},
{
label: 'Underline',
icon: 'format_underlined material-icons',
type: 'button',
cssClass: 'flat',
size: 'iconOnly'
},
{
type: 'separator'
},
{
label: '',
tooltip: 'Font color',
itemTemplate: '
Append to the DOM:
const container = document.getElementById('ribbon-container');
container.appendChild(ribbon);
Remove from the DOM:
ribbon.remove();
Set a property:
ribbon.disabled = true; ribbon.theme = 'dark';
Get a property value:
const isDisabled = ribbon.disabled; const currentTheme = ribbon.theme;
Invoke a method:
ribbon.refresh(); ribbon.focus();
Add event listener:
ribbon.addEventListener('select', (event) => {
console.log('select triggered:', event.detail.oldIndex);
});
Remove event listener:
const handleRibbonEvent = (event) => {
console.log('select triggered:', event.detail.oldIndex);
};
ribbon.addEventListener('select', handleRibbonEvent);
ribbon.removeEventListener('select', handleRibbonEvent);
Accessibility
The Ribbon component follows WAI-ARIA best practices:
- Keyboard navigation - Tab, Arrow keys, Enter, and Escape are supported
- ARIA roles - Appropriate roles and labels are applied automatically
- Focus management - Visible focus indicators for keyboard users
- Screen readers - State changes are announced to assistive technology
- High contrast - Supports Windows High Contrast Mode and forced colors
For custom labeling, set aria-label or aria-labelledby attributes on the component.
Supported stacks: Smart UI targets Angular 17+, React 18+, Vue 3+, Node 18 LTS, and evergreen browsers; pin exact package versions to your org policy.