Skip to main content

Custom Icons

Use this page to extend or override icons in the Widgemo icon registry.

If you need the built-in icon catalog, use Built-in Icons.

When to Use Custom Icons​

SituationPrefer custom icons?Why
Your app uses a branded or shared icon setYesConfig can reference stable icon names
You want to replace a built-in icon globallyYesRe-register the same name
You only need existing built-insNoUse the built-in catalog directly

Register a Custom Icon​

import { widgemoRegistry } from '@widgemo/widgemo-core';
import { CalendarIcon } from '@heroicons/react/24/outline';

widgemoRegistry.registerWidgemoIcon({
	name: 'calendar',
	component: ({ size = 16, className, color = 'currentColor' }) => (
		<CalendarIcon
			width={size}
			height={size}
			className={className}
			style={{ color }}
		/>
	),
});

The icon component receives { size?, className?, color? }.

Registration Contract​

registerWidgemoIcon accepts an IconRegistryEntry:

FieldTypeDescription
namestringIcon name used in config
componentComponentType<{ className?, size?, color? }> | ((props) => ReactNode)Icon renderer
defaultPropsRecord<string, unknown>Optional default props

Built-in Icon Catalog​

Use Built-in Icons for the current built-in icon names and categories.

Override a Built-in Icon​

Register under the same name to replace it globally:

widgemoRegistry.registerWidgemoIcon({
	name: 'edit',
	component: ({ size = 16, color = 'currentColor' }) => (
		<MyCustomEditIcon width={size} style={{ color }} />
	),
});

Fallback and Override Behavior​

  • Unknown icon names fall back to Widgemo's default icon renderer.
  • Re-registering an existing name replaces the prior registration.
  • If a registered custom icon component returns null, that null is rendered; Widgemo does not apply a second fallback after a custom registration is resolved.

Collision Behavior​

Collision semantics are defined in Extension API: Registration Collisions.

Use namespaced names (for example, acme.edit) to reduce accidental collisions.

Using Icons in Config​

Anywhere icon accepts a string, provide the registered name:

actions: [
	{ id: 'schedule', label: 'Schedule', icon: 'calendar', placement: 'pinned' },
]
zones: {
	header: {
		icon: { name: 'calendar', size: 24, color: '#4f46e5' },
	},
}

See Also​