---
description: How to add a custom item to a toolbox.
---

import Image from '@site/src/components/Image';

# Customizing a Blockly toolbox

## 7. Adding a custom toolbox item

In the previous sections we modified the toolbox by extending the base category class.
In this section we will make a completely new toolbox item and add it to our toolbox.

For this example, we are going to create a toolbox label.

### Setup

In the same directory as `index.html` create a new file named `toolbox_label.js`.

Include this file in `index.html`:

```html
<script src="toolbox_label.js"></script>
```

Create a class in `toolbox_label.js` that extends `Blockly.ToolboxItem`
and register it.

```js
class ToolboxLabel extends Blockly.ToolboxItem {
  constructor(toolboxItemDef, parentToolbox) {
    super(toolboxItemDef, parentToolbox);
  }
}

Blockly.registry.register(
  Blockly.registry.Type.TOOLBOX_ITEM,
  'toolboxlabel',
  ToolboxLabel,
);
```

By registering this toolbox item with the name "toolboxlabel" we can now use this
name in our toolbox definition to add our custom item to the toolbox.

Navigate to `index.html`, and scroll down to the toolbox definition. Add a
`<toolboxlabel>` element as the first item in your toolbox definition:

```xml
<toolboxlabel></toolboxlabel>
```

Your toolbox definition should now look something like:

```xml
<xml xmlns="https://developers.google.com/blockly/xml" id="toolbox-categories" style="display: none">
<toolboxlabel></toolboxlabel>
<category css-icon="customIcon fa fa-cog" name="Logic" categorystyle="logic_category">
...
</xml>
```

### Initialize the toolbox item

In order to create a toolbox item we must implement one of the toolbox item interfaces.

For this example, we will be implementing the basic `IToolboxItem` interface.
There are three different types of toolbox item interfaces:
`IToolboxItem`, `ISelectableToobloxItem` and `ICollapsibleToolboxItem`.
Since we do not need our label to be selectable or collapsible, we can implement
the basic `IToolboxItem` interface.

First, we are going to add an init method that will create the dom for our toolbox label:

```js
  /** @override */
  init() {
    // Create the label.
    this.label = document.createElement('label');
    // Set the name.
    this.label.textContent = 'Label';
  }
```

Next, we are going to return this element:

```js
  /** @override */
  getDiv() {
    return this.label;
  }
```

If you open the `index.html` file you should see a label above your first category.

<Image
  src="/images/codelabs/custom-toolbox/toolbox_label.png"
  alt="The toolbox with a label at the top."
  className="codelabImage"
/>

### Add attributes to the toolbox definition

The above code is rather limiting since it only allows us to create a toolbox
label with the text "Label".
To make it possible to create different labels with different text and colour we
are going to add `name` and `colour` attributes to our toolbox definition.

Open `index.html` and navigate to the toolbox definition. Change your
`toolboxlabel` element to look like the below line:

```xml
<toolboxlabel name="Custom Toolbox" colour="darkslategrey"></toolboxlabel>
```

These values will get passed in to our `ToolboxLabel` class through the `toolboxItemDef`.
Navigate to `toolbox_label.js` and add the following lines to your `init` method:

```js
// Set the name.
this.label.textContent = this.toolboxItemDef_['name'];
// Set the color.
this.label.style.color = this.toolboxItemDef_['colour'];
```

Remove the following line from your init method:

```js
this.label.textContent = 'Label';
```

All attributes on our toolbox definition get added to the `toolboxItemDef_`.
`this.toolboxItemDef_` is set in the `Blockly.ToolboxItem` constructor.

Open your `index.html` in a browser to see the updated label.

<Image
  src="/images/codelabs/custom-toolbox/custom_label.png"
  alt='The toolbox with a label that now says "Custom Toolbox".'
  className="codelabImage"
/>

### Add some CSS

Similar to how we added `colour` and `name` above, we are going to add a custom
class to our label.

Navigate to your toolbox definition in `index.html` and modify it to look
like the below line.

```xml
<toolboxlabel name="Label" colour="darkslategrey" css-label="customLabel"></toolboxlabel>
```

Any item that begins with `css-` will be added to a `cssconfig` object stored on
the `toolboxItemDef`.

To use this value navigate to `toolbox_label.js` and add the following lines to
your `init` method.

```js
// Any attributes that begin with css- will get added to a cssconfig object.
const cssConfig = this.toolboxItemDef_['cssconfig'];
// Add the class.
if (cssConfig) {
  this.label.classList.add(cssConfig['label']);
}
```

The above code will add the class to the label. Now, in `toolbox_style.css` add
the below CSS to make the label bold.

```css
.customLabel {
  font-weight: bold;
}
```

### The result

If you open `index.html` you should now see a bold dark gray label at the
top of your toolbox.

<Image
  src="/images/codelabs/custom-toolbox/final_toolbox.png"
  alt="A toolbox with colored background and the blockly label above the category text."
  className="codelabImage"
/>
