Actions

Actions are the buttons in the top and bottom toolbars of the customizer. ChamevoJS ships with built-in actions (undo, download, zoom, etc.) and supports custom actions via web components.

Configuring Action Bars

The actions option controls the top bar and bottomActions controls the bottom bar. Both accept an array of ActionsGroup objects:

const customizer = document.querySelector('cv-customizer');
customizer.options = {
    actions: [
        { items: ['previous-view', 'next-view'], align: 'start' },
        { items: ['undo', 'redo'], align: 'center' },
        { items: ['info', 'download', 'print', 'preview-lightbox', 'reset-product'], align: 'end' },
    ],
    bottomActions: [
        { items: ['zoom-out', 'zoom-slider', 'zoom-in', 'zoom-label', 'zoom-fit'], align: 'start', overflow: 'visible' },
        { items: ['previous-view', 'view-label', 'next-view', 'views-grid'], align: 'end', overflow: 'visible' },
    ],
};

ActionsGroup

Property	Type	Default	Description
items	ActionItem[]	—	Action IDs and/or custom elements to render.
align	'start' | 'center' | 'end'	'start'	Alignment within the bar.
overflow	'collapse' | 'visible'	'collapse'	'collapse' moves items into a dropdown when space is limited. 'visible' keeps them always inline.

Legacy Format

The legacy {left, center, right} format is still supported:

actions: {
    left: ['undo', 'redo'],
    center: [],
    right: ['download', 'print'],
}

Built-in Action IDs

Direct Actions

Execute immediately without UI:

ID	Icon	Description
undo	arrow-u-up-left	Undo last change
redo	arrow-u-up-right	Redo last undone change
previous-view	caret-left	Switch to previous view
next-view	caret-right	Switch to next view
zoom-out	minus	Decrease zoom (min 10%)
zoom-in	plus	Increase zoom (max 200%)
zoom-fit	frame-corners	Reset to auto-fit zoom

Modal Actions

Open a dialog or perform a UI-intensive operation:

ID	Icon	Description
download	download-simple	Export product image (JPEG/PNG/PDF/SVG)
print	printer	Print product via browser
preview-lightbox	eye	Fullscreen preview
reset-product	arrow-counter-clockwise	Reset to initial product state
info	info	Show info modal
guided-tour	compass	Start guided tour (requires guidedTour option)
qr-code	qr-code	Generate and add QR code
save-load	floppy-disk	Save/load designs from browser storage
ai-try-on	sparkle	Open the AI virtual try-on drawer (see AI Try-On)

Widget Actions

Render as interactive controls (never collapsed into dropdowns):

ID	Description
zoom-slider	Interactive zoom slider (10%–200%)
zoom-label	Displays current zoom percentage
view-label	Displays current view position (e.g. "1 / 3")
views-grid	View selector popover grid
ai-try-on	Animated gradient button that opens the AI try-on drawer. See AI Try-On.

Adding Custom Elements to the Action Bar

You can embed custom web components inline in any action group using the ActionCustomElement format:

actions: [
    {
        items: [
            'undo',
            'redo',
            { element: 'my-save-button' },  // Your custom web component
        ],
        align: 'start',
    },
    {
        items: ['download', { element: 'my-share-button' }],
        align: 'end',
    },
],

The custom element tag must be registered in the DOM before the customizer renders. Custom elements are always displayed inline and never collapsed into overflow dropdowns.

Standalone Action Button (cv-action-button)

Use <cv-action-button> to place action buttons anywhere on the page, outside the customizer:

<cv-customizer id="customizer"></cv-customizer>

<!-- Place these anywhere on the page -->
<cv-action-button action="undo"></cv-action-button>
<cv-action-button action="redo"></cv-action-button>
<cv-action-button action="download"></cv-action-button>

The component auto-resolves the icon and label from the action ID. It stays reactive to state changes (e.g. undo disables when nothing to undo).

Properties

Property	Type	Default	Description
action	string	—	Action ID (built-in or custom). Required.
icon	string	Auto-resolved	Override Phosphor icon name.
label	string	Auto-resolved	Override tooltip/aria-label text.
tooltipPlacement	'top' | 'bottom' | 'left' | 'right'	'bottom'	Tooltip direction.

Events

Event	e.detail	Description
cvActionClick	{ action: string }	Fires on click. Call e.preventDefault() to skip built-in handling.

Custom Actions

Use any string as the action — if it's not a built-in ID, only the cvActionClick event fires:

<cv-action-button action="my-share" icon="share-network" label="Share"></cv-action-button>

<script>
document.querySelector('cv-action-button[action="my-share"]')
    .addEventListener('cvActionClick', (e) => {
        // Handle your custom action
        shareProduct();
    });
</script>

Overriding Built-in Actions

Intercept built-in actions and replace their behavior:

<cv-action-button action="download" icon="file-arrow-down" label="Export"></cv-action-button>

<script>
document.querySelector('cv-action-button[action="download"]')
    .addEventListener('cvActionClick', (e) => {
        e.preventDefault(); // Skip built-in download modal
        myCustomExport();   // Your own export logic
    });
</script>

Next Steps

• Options Reference — actions, bottomActions, guidedTour options
• Components — cv-action-button, cv-actions-bar