Filter widgets
When building pages in the Sitefinity WYSIWYG editor, you can control which widgets appear in the widget toolbox by using widget registry filters. Filters are client-side functions that run every time the toolbox is rendered in edit mode.
How widget filtering works
- Filters are attached to your
WidgetRegistryvia its optionalfiltersproperty. - Each filter is evaluated in the browser when the editor renders the toolbox.
- The filter returns whether a widget should be shown.
Keep the default filters when customizing the registry
The SDK’s defaultWidgetRegistry includes built-in filters. If you create a custom registry, it’s recommended to merge:
- The default widgets with your custom widgets
- The default filters with your custom filters
Example:
TypeScript
import { WidgetRegistry, initRegistry, defaultWidgetRegistry } from '@progress/sitefinity-nextjs-sdk';
const customWidgetRegistry: WidgetRegistry = {
widgets: {
// ... your custom widgets
},
filters: [
// ... your custom filters
]
};
customWidgetRegistry.widgets = {
...defaultWidgetRegistry.widgets,
...customWidgetRegistry.widgets
};
// Include default filters with custom filters
customWidgetRegistry.filters = [
...(defaultWidgetRegistry.filters || []),
...(customWidgetRegistry.filters || [])
];
export const widgetRegistry: WidgetRegistry = initRegistry(customWidgetRegistry);Create a custom widget filter
Implement the filter function
Create a client-side TypeScript module (for example components/custom-filters/my-custom-filtering.ts) and add the use client directive at the top so it runs on the client.
The filter function should accept:
widgetMetadata– the widget’s metadataargs– context about the toolbox rendering
It should return a Promise<boolean>:
true→ show the widgetfalse→ hide the widget
Example:
TypeScript
'use client';
import { WidgetMetadata } from '@progress/sitefinity-nextjs-sdk';
import { GetWidgetsArgs } from '@progress/sitefinity-nextjs-sdk';
export async function myCustomFiltering(widgetMetadata: WidgetMetadata, args: GetWidgetsArgs): Promise<boolean> {
// Your filtering logic here
// Return true to show the widget, false to hide it
// Example: Hide a specific widget based on its name
if (widgetMetadata.designerMetadata?.Name === 'MyCustomWidget') {
return false;
}
return true;
}Register the filter in the widget registry
Import your filter into your app’s registry file (commonly src/app/widget-registry.ts) and add it to the filters array.
Example:
TypeScript
import { WidgetRegistry, initRegistry, defaultWidgetRegistry } from '@progress/sitefinity-nextjs-sdk';
import { myCustomFiltering } from './components/custom-filters/my-custom-filtering';
const customWidgetRegistry: WidgetRegistry = {
widgets: {
// your custom widgets here
},
filters: [
myCustomFiltering
]
};
customWidgetRegistry.widgets = {
...defaultWidgetRegistry.widgets,
...customWidgetRegistry.widgets
};
// Include default filters with custom filters
customWidgetRegistry.filters = [
...(defaultWidgetRegistry.filters || []),
...(customWidgetRegistry.filters || [])
];
export const widgetRegistry: WidgetRegistry = initRegistry(customWidgetRegistry);Notes and best practices
- Filters are executed for each widget when the toolbox is drawn, so keep them fast.
- Always start filter modules with
use client, because the widget toolbox runs in the browser. - Prefer additive filtering (hide only what you must), and keep the default filters unless you have a specific reason to replace them.
Want to learn more?
Enhance your Sitefinity skills by enrolling in free training sessions. Become Sitefinity certified through Progress Education Community to strengthen your professional credentials.
Get started with Integration Hub | Sitefinity Cloud
This free lesson teaches administrators, marketers, and other business professionals how to use Sitefinity Integration Hub to create automated workflows between Sitefinity and other business systems.
Web Security for Sitefinity Administrators
This free lesson teaches administrators the basics about protecting your Sitefinity instance and your sites from external threats. Configure HTTPS, SSL, allow lists for trusted sites, and cookie security, among others.
Foundations of Sitefinity ASP.NET Core Development
The free on-demand video course teaches developers how to use Sitefinity ASP.NET Core and take advantage of its decoupled architecture and modern development model.