JupyterLab - UI components written in React
npm install @jupyterlab/ui-componentsThe
@jupyterlab/ui-components
package provides UI elements that are widely used in JupyterLab core,
and that can be reused in your own extensions.
For example, all of the icons in JupyterLab core can be reused viaLabIcon. You can also use LabIcon to create your own custom icons
that will be able to automatically change color to match the current
JupyterLab theme.
LabIcon - set up and render iconsLabIcon is the icon class used by JupyterLab, and is part of the new
icon system introduced in JupyterLab v2.0.
The @jupyterlab/ui-components package provides icons to the rest of
JupyterLab, in the form of a set of LabIcon instances (currently about
80). All of the icons in the core JupyterLab packages are rendered using
one of these LabIcon instances.
You can use any of JupyterLab icons in your own code via an import
statement. For example, to use jupyterIcon you would first do:
``typescript`
import { jupyterIcon } from '@jupyterlab/ui-components';
Icons can be added as children to any div or span nodes using theicon.element(...) method (where icon is any instance of LabIcon).
For example, to render the Jupyter icon you could do:
`typescript`
jupyterIcon.element({
container: elem,
height: '16px',
width: '16px',
marginLeft: '2px'
});
where elem is any HTMLElement with a div or span tag. As shown.element(...)
in the above example, the icon can be styled by passing CSS parameters
into . Any valid CSS parameter can be used (one catch:foo-bar: '8px'
snake case params do have to be converted to camel case: instead of, you’d need to use fooBar: '8px'.
Icons can also be rendered using React. The icon.react parameter holdsicon.react
a standard React component that will display the icon on render. Like
any React component, can be used in various ways.
For example, here is how you would add the Jupyter icon to the render
tree of another React component:
`jsx`
public render() {
return (
"and here's a text node"
);
}
Alternatively, you can just render the icon directly into any existing
DOM node elem by using the ReactDOM module:
`typescript`
const root = createRoot(elem);
root.render(jupyterIcon.react);
If do you use ReactDOM to render, and if the elem node is ever
removed from the DOM, you’ll first need to clean it up:
`typescript`
root.unmount();
This cleanup step is not a special property of LabIcon, but is insteadReactDOM
needed for any React component that is rendered directly at the top
level by .
You can create your own custom icon by constructing a new instance of
LabIcon:
`typescript`
export const fooIcon = new LabIcon({
name: 'barpkg:foo',
svgstr: ''
});
where name should be of the form “your-pkg:icon-name”, and svgstr is
the raw contents of your icon’s svg file.
from an external svg fileAlthough you can copy-and-paste an svg directly into the LabIcon
constructor, the best practice is to keep the svg for each of your icons
in its own separate svg file. You will need to have an filesrc
at the root of your project’s directory:
`typescript
// svg.d.ts
declare module '*.svg' {
const value: string;
export default value;
}
`
You can then import the contents of an svg file:
`typescript
import fooSvgstr from 'path-to-your/foo.svg';
export const fooIcon = new LabIcon({
name: 'barpkg:foo',
svgstr: fooSvgstr
});
`
Example svgs with class annotation can be found in ui-components/style/icons
You can ensure that the colors of your custom LabIcon sync up to theclass
colors of the current JupyterLab theme by adding appropriate
annotations to each colored element of your icon's svg.
In other words, each element of your svg that a fill="..." or astroke="..." property should also have a class="jp-icon
property.
Icon-related CSS classes are defined in ui-components/style/icons.css
All colors shown are for the standard light/dark theme, mouse over for
hex values.
#### jp-iconX: contrast to theme background
Most one-color icons in JupyterLab (including the sidebar and toolbar
icons) are colored using the jp-icon3 class.
For light/dark themes, jp-icon0 corresponds to the darkest/lightestjp-icon1
background color, while is somewhat lighter/darker, and so
forth.
#### jp-icon-accentX: match to theme background
For light/dark themes, jp-icon-accent0 corresponds to thejp-icon-accent1
lightest/darkest background color, while is somewhat
darker/lighter, and so forth.
For most simple, one-color icons, it is desirable for the icon's color
to strongly contrast with that of the application's background. You can
achieve this using one of the jp-iconX classes.
Example: check icon
_svg source:_
`html`
_rendered icon:_
For more complex icons, each element that needs to match the background
should be annotated with a jp-icon-accentX class, while each elementjp-iconX
that needs to contrast with the background should be annotated with a class.
Example: close-circle icon
_svg source:_
`html`
_rendered icon:_
Pre JupyterLab 2.0, most icons were created using the
icons-as-css-background pattern:
- Set up the icon’s svg as a background-image in CSS:
`css
/ CSS /
.jp-FooIcon {
background-image: url('path-to-your/foo.svg');
}
`
- Add the icon to the DOM by constructing an otherwise empty DOM node
with the appropriate class:
`typescript
// typescript
const e = document.createElement('div');
e.className = 'jp-FooIcon';
document.body.append(e);
`
What you end up with is a single DOM node that has the “foo” icon as a
background image.
Post JupyterLab 2.0, nearly all icons in core are now created using
LabIcon
and the icons-as-inline-svg pattern:
- Construct a new instance of LabIcon from the icon’s name and svg:
`typescript
// typescript
// svgstr is the raw contents of an icon's svg file
export const fooIcon = new LabIcon({
name: 'barpkg:foo',
svgstr: ''
});
`
- Add the icon to the DOM using the appropriate property of your
LabIcon instance (either LabIcon.element() to directly create a DOM
node, or LabIcon.react to get the icon as a react component):
`typescript
// typescript
const e = fooIcon.element();
document.body.append(e);
`
What you end up with is a DOM node (by default a ‘div’) that has an
inline svg node as a child.
The big limitation of the old icon-as-css-background pattern is that svg
images rendered as background-image` are invisible to CSS. On the other
hand, an icon rendered as an inline svg node is fully exposed to the
CSS. This allows us to dynamically change icon styling as needed simply by
modifying our CSS. Most importantly, this allows us to recolor icons
according to Jupyterlab’s current theme.