The UI module provides methods for controlling UI components in the Shopware Administration.
modal.open()
Open a modal dialog with custom content or a location.
Modal title displayed in the header
If provided, renders the specified location inside the modal
If no locationId is provided, displays this text content in the modal. Only simple text is supported.
Modal size variant: 'default', 'small', 'large', or 'full'Default: 'default'
Whether to show the modal headerDefault: true
Whether to show the modal footerDefault: true
Whether the modal can be closed by the userDefault: true
Array of button configurations for the modal footer
Returns a promise that resolves when the modal opens
Example - Simple Modal
import { ui } from '@shopware-ag/admin-sdk';
// Open simple text modal
await ui.modal.open({
title: 'Confirmation',
textContent: 'Are you sure you want to continue?',
variant: 'small',
buttons: [
{
label: 'Cancel',
variant: 'ghost',
method: () => {
ui.modal.close();
}
},
{
label: 'Confirm',
variant: 'primary',
method: async () => {
await performAction();
ui.modal.close();
}
}
]
});
Example - Location Modal
import { ui, location } from '@shopware-ag/admin-sdk';
// Register location
location.startRendering('custom-form', (_, { updateHeight }) => {
return `
<form id="custom-form">
<input type="text" name="name" placeholder="Name" />
<textarea name="description" placeholder="Description"></textarea>
</form>
`;
});
// Open modal with location
await ui.modal.open({
title: 'Custom Form',
locationId: 'custom-form',
variant: 'large',
buttons: [
{
label: 'Save',
variant: 'primary',
method: () => {
const form = document.getElementById('custom-form');
const formData = new FormData(form);
saveFormData(formData);
ui.modal.close();
}
}
]
});
Example - Full Screen Modal
await ui.modal.open({
title: 'Preview',
locationId: 'product-preview',
variant: 'full',
showFooter: false,
closable: true
});
modal.close()
Close an open modal.
Optional location ID of the modal to close. If not provided, closes the last opened modal without a locationId.
Returns a promise that resolves when the modal closes
Example
import { ui } from '@shopware-ag/admin-sdk';
// Close specific modal
await ui.modal.close({ locationId: 'custom-form' });
// Close last opened modal
await ui.modal.close();
modal.update()
Update an open modal’s properties.
Location ID of the modal to update
Update button configuration
Returns a promise that resolves when the modal updates
Example
import { ui } from '@shopware-ag/admin-sdk';
// Update modal title and buttons
await ui.modal.update({
locationId: 'custom-form',
title: 'Edit Form (Modified)',
buttons: [
{
label: 'Save Changes',
variant: 'primary',
method: saveChanges
},
{
label: 'Discard',
variant: 'danger',
method: discardChanges
}
]
});
Add a custom menu item to the administration sidebar.
Display label for the menu item
Location ID to render when the menu item is clicked
Show/hide the search bar on the pageDefault: true
Show/hide the smart bar on the pageDefault: true
Parent menu entry under which to display the itemDefault: 'sw-extension'
Position of the menu item in the parent menuDefault: 110
Returns a promise that resolves when the menu item is added
Example
import { ui, location } from '@shopware-ag/admin-sdk';
// Register location
location.startRendering('my-custom-page', () => {
return `
<div class="custom-page">
<h1>My Custom Page</h1>
<p>Content goes here...</p>
</div>
`;
});
// Add menu item
await ui.menu.addMenuItem({
label: 'My Extension',
locationId: 'my-custom-page',
displaySearchBar: true,
displaySmartBar: true,
parent: 'sw-catalogue',
position: 50
});
// Add to different parent menus
await ui.menu.addMenuItem({
label: 'Products Manager',
locationId: 'products-manager',
parent: 'sw-catalogue',
position: 10
});
await ui.menu.addMenuItem({
label: 'Order Analytics',
locationId: 'order-analytics',
parent: 'sw-order',
position: 20
});
await ui.menu.addMenuItem({
label: 'Customer Insights',
locationId: 'customer-insights',
parent: 'sw-customer',
position: 30
});
Collapse the administration sidebar menu.
Returns a promise that resolves when the menu collapses
Example
import { ui } from '@shopware-ag/admin-sdk';
await ui.menu.collapseMenu();
menu.expandMenu()
Expand the administration sidebar menu.
Returns a promise that resolves when the menu expands
Example
import { ui } from '@shopware-ag/admin-sdk';
await ui.menu.expandMenu();
Media Modal
The media modal allows users to select media files from the Shopware media library.
mediaModal.open()
import { ui } from '@shopware-ag/admin-sdk';
const selectedMedia = await ui.mediaModal.open({
allowMultiSelect: false,
});
if (selectedMedia) {
console.log('Selected media:', selectedMedia);
}
Type Definitions
buttonProps
type buttonProps = {
method: () => void;
label: string;
variant?: 'primary'|'ghost'|'danger'|'ghost-danger'|'contrast'|'context';
size?: 'x-small'|'small'|'large';
square?: boolean;
};
uiModalOpen
type uiModalOpen = {
responseType: void;
title?: string;
locationId?: string;
textContent?: string;
variant?: 'default'|'small'|'large'|'full';
showHeader?: boolean;
showFooter?: boolean;
closable?: boolean;
buttons?: buttonProps[];
};
uiModalClose
type uiModalClose = {
responseType: void;
locationId?: string;
};
uiModalUpdate
type uiModalUpdate = {
responseType: void;
locationId: string;
title?: string;
showHeader?: boolean;
showFooter?: boolean;
closable?: boolean;
buttons?: buttonProps[];
};
type menuItemAdd = {
responseType: void;
label: string;
locationId: string;
displaySearchBar?: boolean;
displaySmartBar?: boolean;
parent?: string;
position?: number;
};
Best Practices
Use appropriate modal variants: 'small' for confirmations, 'large' for forms, and 'full' for previews.
Always provide a way to close modals, either through buttons or by keeping closable: true.
Menu items are added under 'sw-extension' by default. Use the parent parameter to organize items under relevant sections.
Button Variants
primary - Primary action button (blue)ghost - Secondary button (transparent)danger - Destructive action (red)ghost-danger - Secondary destructive actioncontrast - High contrast buttoncontext - Contextual action button
Modal Variants
default - Standard modal width (~600px)small - Compact modal (~400px)large - Wide modal (~900px)full - Full screen modal