format-api-f14b86: Document how and where the icon is being imported

[skorasaurus]

I followed along the example of the Format API and but I was dumbfounded because I couldn't figure out how the icon was being imported and needed to import different one.

Action item:
Explicitly mention how the icon is being imported in the tutorial (or if the approach that I did more common, maybe include that )

Other buttons in the format bar were calling it in by importing WordPress' Icons package but that's not called in the format-api-f14b86 example.

I eventually figured out to import an existing WordPress icon by:

1. installing the Icons package (npm install @wordpress/icons --save),
2. in my js file, importing the package and then specifically importing the icon that i wanted to use import { commentReplyLink } from "@wordpress/icons"; List of icons is available at the storybook
3. within my RichTextToolbarButton component, adding the icon as an object like icon={commentReplyLink} unlike the example which in format-api-f14b86 which brings in a text string.

(for anyone else finding this: if you wanted to import your own, you probably could do it through through https://wordpress.github.io/gutenberg/?path=/docs/components-icon--docs

Relatedly, the richtexttoolbarbutton component (which appears to be a wrapper or abstraction?) is could have its documentation improved by although that should go in the gutenberg repository; since all that exists is the example in the rich-text readme and a separate reference in https://github.com/WordPress/gutenberg/tree/1eb76440f7b86ca905ac875d4a2c6ed67fc48daf/packages/block-editor which says it's undocumented.

[juanmaguitar]

Thanks for your feedback on this example @skorasaurus

To change the icon of the RichTextToolbarButton component, you can update the icon prop with the desired Dashicon slug. The Dashicons library provides a wide range of icons you can choose from.

Note

I think all components with an icon property are actually using an <Icon> component, which admits a dashicon slug, a SVG, or another component (the example you provide with commentReplyLink would be this case) to customize the icon

Here's an example of how you can change the icon of RichTextToolbarButton:

import { RichTextToolbarButton } from '@wordpress/block-editor';

const MyCustomButton = () => {
  return (
    <RichTextToolbarButton
      icon="admin-site"
      title="My Custom Button"
      onClick={() => {
        // Handle button click event
      }}
    />
  );
};

In the example above, the icon prop is set to admin-site, corresponding to the Dashicon for a site icon. You can replace admin-site with the Dashicon slug of your desired icon. You can find a list of available Dashicons and their corresponding slugs in the Dashicons documentation.

Relatedly, the richtexttoolbarbutton component (which appears to be a wrapper or abstraction?) is could have its documentation improved by although that should go in the gutenberg repository; since all that exists is the example in the rich-text readme and a separate reference in https://github.com/WordPress/gutenberg/tree/1eb76440f7b86ca905ac875d4a2c6ed67fc48daf/packages/block-editor which says it's undocumented.

As it states here the RichTextToolbarButton is a specific "slot" to extend the format toolbar, so you're right saying it's kind of a wrapper.

Read more about Slot and Fills in the Block Editor Handbooks' SlotFills Reference or the Extending plugins using custom SlotFills article in the Developer blog

I agree there's a lot of room for improvement in the docs, so please open an issue at https://github.com/WordPress/gutenberg/issues for any improvement you consider should be done in the docs, so actions can be taken from there.

[juanmaguitar]

@skorasaurus I think we can close this issue. What do you think?
For improvement requests/suggestions on the Format API the best place to open an issue is https://github.com/WordPress/gutenberg/issues

[skorasaurus]

@juanmaguitar thanks for following up and for the very detailed reply.

I was a bit frustrated when I filed the issue and will file an issue in gutenberg to propose that RichTextToolbarButton has its props (or parameters?) documented.

I'll propose and credit you for writing:
the icon prop is set to admin-site, corresponding to the Dashicon for a site icon. You can replace admin-site with the Dashicon slug of your desired icon. You can find a list of available Dashicons and their corresponding slugs in the Dashicons documentation.