---
description: What workspace comments are and how to use them.
title: Workspace comments
image: images/blockly_banner.png
---

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

# Workspace comments

A workspace comment is a graphical element that you can enter text into. Usually
it's used to document things about your code, just like comments in a text-based
programming language.

<Image
  alt="Workspace comment"
  src="/images/workspace-comments/workspace-comment.png"
  width={150}
/>

:::note
workspace comments cannot be added to the [flyout][flyout].
:::

## Enable workspace comments

To enable workspace comments in your application, you need to give users some
way to create them. One way to do this is to add a context menu item that
creates a workspace comment. You can register default context menu items to
create, delete, and duplicate workspace comments with the following code:

```js
// This should be called on page load. It can be called before or after
// you inject your workspace.
Blockly.ContextMenuItems.registerCommentOptions();
```

You could also create your own context menu options, or add another way for the
user to add workspace comments. For more information about context menu options,
see [Context menus][context-menus].

## Visually customize comments

There are several ways for you to customize the look of workspace comments.
These use CSS and not [themes][themes]. It is possible to control most of the
colours and sizes of different parts of the comment, but not how they are
positioned.

### Colour CSS variables

You can set the `commentFillColour` css variable to change the background colour
of the text area. You can set the `commentBorderColour` css variable to change
the colour of the comment top bar and the border of the comment.

```css
.blocklyWorkspace {
  --commentFillColour: blue;
  --commentBorderColour: red;
}
```

<Image
  alt="A workspace comment with the colours changed"
  src="/images/workspace-comments/coloured-comment.png"
  width={150}
/>

### CSS classes

There are different css classes assigned to different elements of the comment
view, which allow you to modify the elements' styling.

| CSS class(es)                                | Image                                                                                                                                                                                                             |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- |
| `blocklyComment`, `blocklyDraggable`         | <Image alt="Workspace comment" src="/images/workspace-comments/workspace-comment-outline.png" width={150} />                                                                                                      |
| `blocklySelected`, `blocklyCommentHighlight` | <Image alt="Selected comment" src="/images/workspace-comments/selected-comment.png" width={150} /> <Image alt="Selected collapsed comment" src="/images/workspace-comments/selected-collapsed.png" width={150} /> | :   |
| `blocklyCollapsed`                           | <Image alt="Collapsed workspace comment" src="/images/workspace-comments/collapsed-outline.png" width={150} />                                                                                                    |
| `blocklyCommentTopbar`                       | <Image alt="Workspace comment topbar" src="/images/workspace-comments/top-bar-outline.png" width={150} />                                                                                                         |
| `blocklyFoldoutIcon`                         | <Image alt="Foldout icon" src="/images/workspace-comments/foldout-icon-outline.png" width={150} />                                                                                                                |
| `blocklyCommentPreview`, `blocklyText`       | <Image alt="Comment preview" src="/images/workspace-comments/preview-text-outline.png" width={150} />                                                                                                             |
| `blocklyDeleteIcon`                          | <Image alt="Delete icon" src="/images/workspace-comments/delete-icon-outline.png" width={150} />                                                                                                                  |
| `blocklyText`                                | <Image alt="Text" src="/images/workspace-comments/text-input-outline.png" width={150} />                                                                                                                          |
| `blocklyResizeHandle`                        | <Image alt="Resize icon" src="/images/workspace-comments/resize-handle-outline.png" width={150} />                                                                                                                |

#### Basic CSS use

In most cases you can apply your custom attributes with the appropriate CSS
class:

```css
.blocklyCommentTopbarBackground {
  height: 50px;
}
```

<Image
  alt="A workspace comment with a taller top bar"
  src="/images/workspace-comments/tall-top-bar.png"
  width={150}
/>

#### CSS for text

However, for text you need to be more specific to override the CSS generated by
the renderer.

```css
/* Modifies the preview text. */
.blocklyComment .blocklyCommentPreview.blocklyText {
  fill: blue;
}

/* Modifies the input text. */
.blocklyComment .blocklyText {
  color: blue;
}
```

<Image
  alt="A workspace comment with blue preview text"
  src="/images/workspace-comments/blue-preview-text.png"
  width={150}
/>

<Image
  alt="A workspace comment with blue input text"
  src="/images/workspace-comments/blue-text.png"
  width={150}
/>

#### CSS for selected highlights

And for highlighting the comment when its selected, the object the CSS should be
applied to changes depending on whether the comment is collapsed or not. When
it's collapsed, you apply the CSS to the `blocklyCommentTopbarBackground`,
otherwise apply it to the `blocklyCommentHighlight`.

```css
/* Highlight when expanded. */
.blocklySelected .blocklyCommentHighlight {
  stroke: #fc3;
  stroke-width: 3px;
}

/* Hide normal highlight when collapsed. */
.blocklyCollapsed.blocklySelected .blocklyCommentHighlight {
  stroke: none;
}

/* Instead apply the collapsed highlight to the top bar. */
.blocklyCollapsed.blocklySelected .blocklyCommentTopbarBackground {
  stroke: #fc3;
  stroke-width: 3px;
}
```

### Icons

The `blocklyFoldoutIcon`, `blocklyDeleteIcon`, and `blocklyResizeHandle` classes
are all applied to [`<image>`][svg-image-element] elements. This means that if
you want to change the colour or shape of an icon, you can include a different
image in your [media folder][media].

| Image name          | Image                                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------- |
| `foldout-icon.svg`  | <Image alt="Foldout icon" src="/images/workspace-comments/foldout-icon-outline.png" width={150} /> |
| `delete-icon.svg`   | <Image alt="Delete icon" src="/images/workspace-comments/delete-icon-outline.png" width={150} />   |
| `resize-handle.svg` | <Image alt="Resize icon" src="/images/workspace-comments/resize-handle-outline.png" width={150} /> |

#### Delete icon

The delete icon is hidden by default. If you want to enable it, you need to use
CSS to make it visible:

```css
.blocklyDeleteIcon {
  display: block;
}
```

### Default size

To set the default comment size, set the static property
`Blockly.comments.CommentView.defaultCommentSize`:

```js
Blockly.comments.CommentView.defaultCommentSize = new Blockly.utils.Size(
  200,
  200,
);
```

[context-menus]: /guides/configure/context-menus
[flyout]: /guides/get-started/workspace-anatomy#flyout-toolbox
[themes]: /guides/configure/appearance/themes
[svg-image-element]: https://developer.mozilla.org/en-US/docs/Web/SVG/Element/image
[media]: /guides/configure/media
[workspace-comment-image]: /images/workspace-comments/workspace-comment.png
[coloured-workspace-comment-image]: /images/workspace-comments/coloured-comment.png
[workspace-comment-outline-image]: /images/workspace-comments/workspace-comment-outline.png
[collapsed-outline-image]: /images/workspace-comments/collapsed-outline.png
[top-bar-outline-image]: /images/workspace-comments/top-bar-outline.png
[foldout-icon-outline-image]: /images/workspace-comments/foldout-icon-outline.png
[preview-text-outline-image]: /images/workspace-comments/preview-text-outline.png
[delete-icon-outline-image]: /images/workspace-comments/delete-icon-outline.png
[text-outline-image]: /images/workspace-comments/text-input-outline.png
[resize-handle-outline-image]: /images/workspace-comments/resize-handle-outline.png
[taller-top-bar-image]: /images/workspace-comments/tall-top-bar.png
[blue-input-text-image]: /images/workspace-comments/blue-text.png
[blue-preview-text-image]: /images/workspace-comments/blue-preview-text.png
[selected-comment]: /images/workspace-comments/selected-comment.png
[selected-collapsed]: /images/workspace-comments/selected-collapsed.png
