## Usage

The RichTextEditor allows user to add special formatting to the text. Using this editor, user can bold, underline, change colour and fonts, add hyperlinks, add lists and tables, insert video/images etc.

<Notice>
  <Text>
    When users are allowed to add simple text that doesn't require formatting, use a{' '}
    <Link label="TextareaInput" href="/packages/text-area-input" /> instead.
  </Text>
</Notice>

<Notice>
  <Text>
    Pass the `licenseKey` prop to override the default key. Premium features, including AI, require a valid CKEditor 5 commercial license.
  </Text>
  <Text>
    To use AI-powered features, pass `aiApiUrl` and ensure your license includes them. Set `isAiDisabled` to disable AI. See the{' '}
    <Link
      label="CKEditor AI assistant integration guide"
      href="https://ckeditor.com/docs/ckeditor5/latest/features/ai-assistant/ai-assistant-integration.html"
    />{' '}
    for details.
  </Text>
</Notice>

## Toolbar position

The placement of the toolbar can be either at the top or bottom; it depends on the context of your application. EDS recommends:

### Place it at the top

If it contains actions that users need to access frequently and formatting is the primary goal for the user. For example, it is used for creating job descriptions, editing documents, crafting certificate templates, and writing HTML/Markdown, etc.

```tsx live
return <RichTextEditor />;
```

## Height

By default, the RichTextEditor starts at `150` and grows up to `400`. These props use numbers, and the values are treated as pixels.

Once the editor reaches `maxHeight`, the content area scrolls and the toolbar stays fixed at the top.

### Min-height

Use the `minHeight` prop to set the minimum height of the editor.

```tsx live
return (
  <Flex flexDirection="column" gap="small">
    <RichTextEditor minHeight={240} />
    <RichTextEditor
      minHeight={240}
      defaultValue={`
<h2>From Chaos to Clarity: The Power of Clear Expectations&nbsp;</h2>
<h3>Introduction&nbsp;</h3>
In the fast-paced world we navigate today, clarity is often the beacon that guides us through the chaos. This writing explores the transformative power of clear expectations and how they serve as the cornerstone for building order out of disorder.&nbsp;

<h3>The Landscape of Chaos&nbsp;</h3>
In our personal and professional lives, chaos can manifest in various forms – miscommunication, uncertainty, and unmet expectations. The consequences of this chaos can be detrimental, leading to stress, inefficiency, and strained relationships. However, amidst the chaos, a simple yet potent tool emerges – clear expectations.

<h3>Defining Clear Expectations&nbsp;</h3>
Understanding what clear expectations entail is crucial. It involves articulating precisely what is expected, setting realistic goals, and establishing transparent communication channels. Clarity in expectations lays the groundwork for structured processes and positive outcomes.

<h3>The Role of Communication&nbsp;</h3>
At the heart of clear expectations is effective communication. Whether in a team project, a personal relationship, or a professional setting, communication serves as the bridge that connects intentions with understanding. This section delves into the art of communicating expectations and the impact it has on fostering a culture of clarity.

<h3>Navigating Challenges&nbsp;</h3>
Despite our best efforts, challenges are inevitable. This section explores common obstacles that may hinder the establishment of clear expectations and provides strategies for overcoming them. From addressing misunderstandings to adapting to unforeseen changes, proactive measures can transform challenges into opportunities for growth.

<h3>Case Studies: Realizing the Benefits&nbsp;</h3>
Examining real-world scenarios, this segment illustrates how individuals and organizations have experienced tangible benefits by embracing the power of clear expectations. From improved productivity in the workplace to stronger personal relationships, these case studies serve as testimonials to the transformative influence of clarity.
`}
    />
  </Flex>
);
```

### Max-height

Use the `maxHeight` prop to set the maximum height before the content starts scrolling.

```tsx live
return (
  <Flex flexDirection="column" gap="small">
    <RichTextEditor maxHeight={240} />
    <RichTextEditor
      maxHeight={240}
      defaultValue={`
<h2>From Chaos to Clarity: The Power of Clear Expectations&nbsp;</h2>
<h3>Introduction&nbsp;</h3>
In the fast-paced world we navigate today, clarity is often the beacon that guides us through the chaos. This writing explores the transformative power of clear expectations and how they serve as the cornerstone for building order out of disorder.&nbsp;

<h3>The Landscape of Chaos&nbsp;</h3>
In our personal and professional lives, chaos can manifest in various forms – miscommunication, uncertainty, and unmet expectations. The consequences of this chaos can be detrimental, leading to stress, inefficiency, and strained relationships. However, amidst the chaos, a simple yet potent tool emerges – clear expectations.

<h3>Defining Clear Expectations&nbsp;</h3>
Understanding what clear expectations entail is crucial. It involves articulating precisely what is expected, setting realistic goals, and establishing transparent communication channels. Clarity in expectations lays the groundwork for structured processes and positive outcomes.

<h3>The Role of Communication&nbsp;</h3>
At the heart of clear expectations is effective communication. Whether in a team project, a personal relationship, or a professional setting, communication serves as the bridge that connects intentions with understanding. This section delves into the art of communicating expectations and the impact it has on fostering a culture of clarity.

<h3>Navigating Challenges&nbsp;</h3>
Despite our best efforts, challenges are inevitable. This section explores common obstacles that may hinder the establishment of clear expectations and provides strategies for overcoming them. From addressing misunderstandings to adapting to unforeseen changes, proactive measures can transform challenges into opportunities for growth.

<h3>Case Studies: Realizing the Benefits&nbsp;</h3>
Examining real-world scenarios, this segment illustrates how individuals and organizations have experienced tangible benefits by embracing the power of clear expectations. From improved productivity in the workplace to stronger personal relationships, these case studies serve as testimonials to the transformative influence of clarity.
`}
    />
  </Flex>
);
```

## Word count and character count

Use `showWordCount` to display the current word and character count below the editor.

```tsx live
return <RichTextEditor showWordCount />;
```

## Max word and char count

<Badge label="Coming soon" tone="informative" />
Validation for max character count and max word count is coming soon!

## Accessing the editor instance

The RichTextEditor supports React refs, allowing you to programmatically interact with the CKEditor instance. This is useful when you need to get or set editor content, focus the editor, or perform other imperative editor operations.

### Using with TypeScript

```tsx skip-typecheck
import { useRef } from 'react';
import { RichTextEditor, type RichTextEditorInstance } from '@eds/rich-text-editor';

const MyComponent = () => {
  const editorRef = useRef<RichTextEditorInstance>(null);

  const handleGetContent = () => {
    if (editorRef.current) {
      const content = editorRef.current.getData();
      console.log('Editor content:', content);
    }
  };

  const handleSetContent = () => {
    if (editorRef.current) {
      editorRef.current.setData('<p>New content</p>');
    }
  };

  const handleFocus = () => {
    if (editorRef.current) {
      editorRef.current.editing.view.focus();
    }
  };

  return (
    <>
      <RichTextEditor ref={editorRef} />
      <button onClick={handleGetContent}>Get Content</button>
      <button onClick={handleSetContent}>Set Content</button>
      <button onClick={handleFocus}>Focus Editor</button>
    </>
  );
};
```

### Ref vs onReady callback

You can use either refs or the `onReady` callback to access the editor instance. Choose based on your preference:

- **Ref**: Better for imperative operations or when you need access to the editor instance at specific times
- **onReady callback**: Better for setup logic that should run when the editor initializes

```tsx skip-typecheck
// Using ref
const editorRef = useRef<RichTextEditorInstance>(null);
<RichTextEditor ref={editorRef} />;

// Using onReady callback
<RichTextEditor
  onReady={(editor) => {
    editor.editing.view.focus();
  }}
/>;
```

Both approaches can be used together in the same component.

## Event handlers

The RichTextEditor supports standard focus and blur event handlers, allowing you to track when the editor receives or loses focus. This is useful for form validation, tracking user interactions, or triggering side effects.

### onFocus

The `onFocus` callback is called when the editor receives focus:

```tsx skip-typecheck
import { RichTextEditor } from '@eds/rich-text-editor';

const MyComponent = () => {
  const handleFocus = () => {
    console.log('Editor focused');
  };

  return <RichTextEditor onFocus={handleFocus} />;
};
```

### onBlur

The `onBlur` callback is called when the editor loses focus:

```tsx skip-typecheck
import { RichTextEditor } from '@eds/rich-text-editor';

const MyComponent = () => {
  const handleBlur = () => {
    console.log('Editor blurred');
  };

  return <RichTextEditor onBlur={handleBlur} />;
};
```

## Custom Plugins

The RichTextEditor component supports loading custom CKEditor 5 plugins, allowing you to extend its functionality with your own features. This is particularly useful when you need application-specific functionality that isn't provided by the default plugins.

> **Note:** Custom plugins should be used as a last resort. Before creating a custom plugin, check if the existing toolbar configuration and built-in features can meet your needs. Custom plugins add complexity and maintenance overhead, so use them sparingly and only when truly necessary.

### Basic usage

To add custom plugins, use the `extraPlugins` prop along with `additionalConfig` to customize the toolbar and plugin settings:

```tsx skip-typecheck
import { RichTextEditor } from '@eds/rich-text-editor';
import { MyCustomPlugin } from './MyCustomPlugin';

const MyComponent = () => {
  return (
    <RichTextEditor
      extraPlugins={[MyCustomPlugin]}
      additionalConfig={{
        toolbar: {
          items: ['bold', 'italic', '|', 'myCustomButton'],
        },
      }}
    />
  );
};
```

### Creating a custom plugin

Here's an example of creating a simple custom plugin that inserts timestamps:

```typescript skip-typecheck
// InsertTimestampPlugin.ts
import { Plugin, ButtonView, Command } from '@eds/rich-text-editor/plugin-api';
import type { Editor } from '@eds/rich-text-editor/plugin-api';

// The plugin API entrypoint is client-only.
// Import it only from plugin files that are dynamically loaded on the client.

class InsertTimestampCommand extends Command {
  execute() {
    const editor = this.editor;
    const timestamp = new Date().toLocaleString();

    editor.model.change((writer) => {
      const position = editor.model.document.selection.getFirstPosition();
      if (position) {
        editor.model.insertContent(writer.createText(timestamp), position);
      }
    });
  }

  refresh() {
    this.isEnabled = this.editor.model.document.selection.getFirstPosition() !== null;
  }
}

export class InsertTimestampPlugin extends Plugin {
  static get pluginName() {
    return 'InsertTimestamp';
  }

  init() {
    const editor = this.editor;

    // Register command
    editor.commands.add('insertTimestamp', new InsertTimestampCommand(editor as Editor));

    // Add toolbar button
    editor.ui.componentFactory.add('insertTimestamp', (locale) => {
      const view = new ButtonView(locale);
      const command = editor.commands.get('insertTimestamp');

      view.set({
        label: 'Insert Timestamp',
        withText: true,
        tooltip: true,
      });

      if (command) {
        view.bind('isEnabled').to(command, 'isEnabled');
      }

      view.on('execute', () => {
        editor.execute('insertTimestamp');
        editor.editing.view.focus();
      });

      return view;
    });
  }
}
```

If you need to keep the plugin client-only in an SSR environment, load the plugin file dynamically and then pass it into `extraPlugins`.

### Using multiple custom plugins

You can load multiple custom plugins at once:

```tsx skip-typecheck
import { RichTextEditor } from '@eds/rich-text-editor';
import { InsertTimestampPlugin } from './plugins/InsertTimestampPlugin';
import { CustomHighlightPlugin } from './plugins/CustomHighlightPlugin';

const MyComponent = () => {
  return (
    <RichTextEditor
      extraPlugins={[InsertTimestampPlugin, CustomHighlightPlugin]}
      additionalConfig={{
        toolbar: {
          items: ['bold', 'italic', 'underline', '|', 'insertTimestamp', 'customHighlight'],
        },
      }}
    />
  );
};
```

### Advanced plugin configuration

The `additionalConfig` prop allows you to pass plugin-specific configuration:

```tsx skip-typecheck
<RichTextEditor
  extraPlugins={[MentionPlugin]}
  additionalConfig={{
    mention: {
      feeds: [
        {
          marker: '@',
          feed: ['@john', '@jane', '@admin'],
          minimumCharacters: 1,
        },
      ],
    },
  }}
/>
```

### Resources

- [CKEditor 5 Plugin Development Guide](https://ckeditor.com/docs/ckeditor5/latest/framework/tutorials/crash-course/plugins.html)
- [Creating Custom Commands](https://ckeditor.com/docs/ckeditor5/latest/framework/architecture/core-editor-architecture.html#commands)
- [UI Components](https://ckeditor.com/docs/ckeditor5/latest/framework/architecture/ui-library.html)

The rich-text editor (aka. WYSIWYG) allows user to format text using an editing area. This component uses CKEditor under the hood.

RichTextEditor

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Popover

Radio

RailTrack

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources