Icons
Since Panel 1.2.11 every icon slot in the extension API takes the same type, IconLike. A route icon, a context menu item, a permission group icon and your extension's cardIcon all accept a Font Awesome icon, a React element or a component. Before 1.2.11 some of these slots wanted an IconDefinition and others a rendered ReactNode, so you had to check each one.
The IconLike Type
import type { IconLike } from '@/elements/data-display/Icon.tsx';
type IconLike = IconDefinition | ReactElement | ComponentType<{ className?: string }>;| Form | Example | Use it for |
|---|---|---|
IconDefinition | faCube | Any Font Awesome icon. This is the usual choice and matches the rest of the Panel. |
ReactElement | <img src='/my-extension/logo.svg' alt='' /> | Something already rendered, such as an image, or a <FontAwesomeIcon /> with its own props. |
ComponentType | MyLogoIcon | Your own SVG icon. The Panel renders it in a 1em box like a Font Awesome icon and stretches it to fill that box. |
You don't need to wrap Font Awesome icons any more. These two lines render the same icon:
<TitleCard title='Players' icon={faUsers}>
<TitleCard title='Players' icon={<FontAwesomeIcon icon={faUsers} />}>The second form still works, so code written for older Panels keeps compiling.
Rendering an Icon Yourself
If your own component takes an icon prop, type it as IconLike and render it with Icon:
import Icon, { type IconLike } from '@/elements/data-display/Icon.tsx';
function StatusRow({ icon, label }: { icon: IconLike; label: string }) {
return (
<div className='flex items-center gap-2'>
<Icon icon={icon} className='text-(--mantine-color-dimmed)' />
{label}
</div>
);
}Icon takes the same props as FontAwesomeIcon (size, className, style, color and so on), but icon is an IconLike. Each form renders a little differently:
- An
IconDefinitionrenders as a regularFontAwesomeIcon. - A
<FontAwesomeIcon />or<Icon />element gets your props merged into its own, with both sets of class names kept. - Any other element or component renders inside a
<span>that takes the same 1em box as a Font Awesome icon, so it lines up with text and picks upsize,className,color,styleand a tooltip's ref. A component is stretched to fill that box. An element keeps the size it already has, so a 16px spinner stays 16px.
Where IconLike Is Accepted
On the extension registry:
| Where | Field |
|---|---|
| Routes | icon |
| Sub-navigation tabs | icon |
| Context menu items | icon |
| File icon handlers | the return value |
| Quick actions | icon on actions, mode items and categories |
| Keyboard shortcut categories | icon |
| Permission groups | the icon argument |
| Form sections | icon |
| Theme variants | icon |
| Toast actions | icon |
The Extension class | cardIcon |
And on these Panel components, which you can use in your own pages:
| Component | Import | Props |
|---|---|---|
Alert | @/elements/feedback/Alert.tsx | icon |
TitleCard | @/elements/data-display/TitleCard.tsx | icon |
EmptyState | @/elements/feedback/EmptyState.tsx | icon |
StatCard | @/elements/data-display/StatCard.tsx | icon, popoverIcon |
CollapsibleSection | @/elements/CollapsibleSection.tsx | icon |
ChartBlock | @/elements/charts/ChartBlock.tsx | icon |
BlockedOverlay | @/elements/feedback/BlockedOverlay.tsx | icon |
KbdKey | @/elements/typography/KbdKey.tsx | icon |
CapacityCard | @/elements/admin/CapacityCard.tsx | icon |
AllocationBar | @/elements/admin/AllocationBar.tsx | icon |
ChartBlock's overlayIcon is still a plain ReactNode, because it usually holds a loading spinner. Mantine's own components and props, such as leftSection on buttons and inputs, also still take a ReactNode, so wrap the icon there yourself.
Replacing the Panel's Icons
An extension can swap any Font Awesome icon the Panel renders for one of its own:
import { faServer } from '@fortawesome/free-solid-svg-icons';
import { Extension, ExtensionContext } from 'shared';
import MyServerIcon from './MyServerIcon.tsx';
class MyExtension extends Extension {
public initialize(ctx: ExtensionContext): void {
ctx.extensionRegistry.enterIcons((icons) => icons.replaceIcon(faServer, MyServerIcon));
}
}
export default new MyExtension();The first argument is the icon to replace, and the second is any IconLike, including another Font Awesome icon. The replacement applies everywhere that icon is drawn: the sidebar, menus, buttons, file rows, toasts, and other extensions' UI too, because every FontAwesomeIcon in the Panel goes through the same component.
Replacements match on the icon's style and name:
- Font Awesome exports some icons under more than one name, such as
faCogandfaGear. Replacing either name replaces both. - Each style is a separate icon. Replacing the solid
faServerleaves the regular one alone. - A replacement covers every place the icon appears, and you can't limit it to one. The Panel uses
faServerfor both Nodes and Database Agent Hosts in the admin sidebar, so replacing it changes both entries.
When two extensions replace the same icon, the one loaded later wins. Replacements from a disabled extension are not applied.
INFO
Icons an admin has picked in the Panel, such as a custom sidebar icon in the route order editor or an OAuth provider icon, are never replaced.
Only Font Awesome icons can be replaced this way. Mantine draws some icons itself, such as the chevrons in selects and the close button on modals, and the Panel's logo is an image. To change those, hook the component that draws them through the hookable components system.
Only While a Theme Variant Is Active
A theme variant can replace icons from its enter hook. They are restored when the variant stops being active:
themes.addVariant({
id: 'my-extension-retro',
label: 'Retro',
schemes: ['dark'],
enter(scope) {
scope.replaceIcon(faServer, RetroServerIcon).replaceIcon(faUsers, RetroUsersIcon);
},
});A replacement from a theme variant takes priority over one from replaceIcon on the registry.