Custom icon in a launcher card

[jtpio]

At the moment in 1.x, users can pass an iconClass to a command:

commands.addCommand(command, {
  label: 'Custom Command',
  caption: 'Launch Custom Command',
  iconClass: args => (args['isPalette'] ? '' : 'jp-CustomIcon'),
  ...
});

And define an icon as CSS background:

.jp-CustomIcon {
  background-image: url('custom.svg');
}

The icon should show up correctly in the launcher card.

In 2.x, it looks like the DOM element is not created unless a new LabIcon was instantiated beforehand:

jupyterlab/packages/ui-components/src/icon/labicon.tsx

Lines 218 to 221 in b66bb79

	if (LabIcon._instancesByNameAndClassName.has(className)) {
	const icon = LabIcon._instancesByNameAndClassName.get(className)!;
	return <icon.react {...props} />;
	}

See this commit as an example: jupyterlab/extension-examples@b81943d

It works for the default icons in core because their LabIcon is defined in iconimports.ts.

I wonder if the behavior in 1.x should be kept (keeping the DOM element with the CSS class)? When a user sees "class" in iconClass, she might expect it to correspond to the class added to the DOM element, which could then be styled in CSS.

Maybe something to consider in #7864? cc @telamonian

[telamonian]

What you described was indeed the intended behavior (if no LabIcon existed matching iconClass, it was supposed to render a blank div with class=iconClass), but basically UNSTABLE_getReact had some problems (there was a reason I marked it UNSTABLE) and couldn't handle this situation correctly.

#7864 is now done, and it should make things much simpler. Every interface that has an .iconClass field now also has an .icon field, and they are completely orthogonal. For example, you can set a LabIcon on a command like so:

commands.addCommand(command, {
  icon: args => args['isPalette'] ? undefined : fooIcon,
  ...
});

and if you want the old icon-as-css-background behavior, you can just use iconClass the same way as you did in 1.x, unchanged:

commands.addCommand(command, {
  iconClass: args => (args['isPalette'] ? '' : 'jp-CustomIcon'),
  ...
});

If for whatever reason you set both icon and iconClass, iconClass will be ignored.

[jtpio]

Thanks @telamonian.

Indeed it sounds like we can consolidate the documentation to make these cases more discoverable to extension developers.

[jtpio]

This should now be fixed in 2.0, thanks @telamonian!