Md Editor Rt

https://imzbf.github.io/md-editor-rt/en-US/api
Admin
Md Editor Rt is a Markdown editor for React, developed in JSX and TypeScript, which supports...
Tokens:14,175
Snippets:138
Trust Score:8.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Initialize MdEditor with ExposeParam

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Setup the editor instance using a React ref to access exposed methods.

```jsx
import React, { useState, useEffect, useRef } from 'react';
import { MdEditor, ExposeParam } from 'md-editor-rt';
//
// import type { ExposePreviewParam } from 'md-editor-rt';
import 'md-editor-rt/lib/style.css';

export default () => {
  const [text, setText] = useState('#Hello Editor');

  const editorRef = useRef<ExposeParam>();

  useEffect(() => {
    editorRef.current?.on('catalog', console.log);
  }, []);

  return <MdEditor ref={editorRef} modelValue={text} onChange={setText} />;
};
```

--------------------------------

### getEditorView()

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Get codemirror instance.

```APIDOC
## getEditorView()

### Description
Returns the underlying CodeMirror instance used by the editor.
```

--------------------------------

### on(event, callback)

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Get the internal state of the editor, including pageFullscreen, fullscreen, preview, htmlPreview, and catalog.

```APIDOC
## on(event, callback)

### Description
Listens for changes to the internal state of the editor.

### Parameters
- **event** (string) - The event name to listen to (e.g., 'pageFullscreen', 'fullscreen', 'preview', 'previewOnly', 'htmlPreview', 'catalog').
- **callback** (function) - Function to execute when the state changes, receiving the status as an argument.
```

--------------------------------

### Configure Markdown-it Anchor

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Example of using markdown-it-anchor to add permalinks to titles.

```javascript
import { config } from 'md-editor-rt';
import ancher from 'markdown-it-anchor';

config({
  markdownItConfig(mdit) {
    mdit.use(ancher, {
      permalink: true
    });
  }
});
```

--------------------------------

### Get Selected Text

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Retrieve the text currently highlighted in the editor.

```js
console.log(editorRef.current?.getSelectedText());
```

--------------------------------

### Add Line Numbers Extension

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Example of adding the line numbers extension to the editor via the config function.

```javascript
import { config } from 'md-editor-rt';
import { lineNumbers } from '@codemirror/view';

config({
  codeMirrorExtensions(_theme, extensions) {
    return [
      ...extensions,
      {
        type: 'lineNumbers',
        extension: lineNumbers()
      }
    ];
  }
});
```

--------------------------------

### getSelectedText()

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Get the currently selected text.

```APIDOC
## getSelectedText()

### Description
Returns the text currently selected in the editor.
```

--------------------------------

### Modify Image Plugin Class

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Example of modifying the options of a built-in markdown-it plugin.

```javascript
import { config } from 'md-editor-rt';

config({
  markdownItPlugins(plugins) {
    return plugins.map((p) => {
      if (p.type === 'image') {
        return {
          ...p,
          options: {
            ...p.options,
            classes: 'my-class'
          }
        };
      }

      return p;
    });
  }
});
```

--------------------------------

### config({ katexConfig })

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Configure the katex math rendering settings by providing a callback that receives the base configuration.

```APIDOC
## config({ katexConfig })

### Description
Configure `katex` settings by modifying the base configuration object.

### Usage
```javascript
import { config } from 'md-editor-rt';

config({
  katexConfig(base: any) {
    return {
      ...base,
      strict: false,
    };
  },
});
```
```

--------------------------------

### Configure Preview Theme

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Define custom CSS for preview themes and apply them via the previewTheme prop.

```css
.xxx-theme {
  color: red;
}
```

```jsx
<MdEditor previewTheme="xxx" />
```

--------------------------------

### config({ mermaidConfig })

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Configure the mermaid diagram rendering settings by providing a callback that receives the base configuration.

```APIDOC
## config({ mermaidConfig })

### Description
Configure `mermaid` settings by modifying the base configuration object.

### Usage
```javascript
import { config } from 'md-editor-rt';
config({
  mermaidConfig(base: any) {
    return {
      ...base,
      logLevel: 'error',
    };
  },
});
```
```

--------------------------------

### Import Internal Configurations

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Access internal constants and configurations provided by the library.

```js
import { allToolbar, allFooter, zh_CN, en_US, editorExtensionsAttrs } from 'md-editor-rt';

console.log(allToolbar, allFooter, zh_CN, en_US, editorExtensionsAttrs);
```

--------------------------------

### Configure Editor Extensions

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Define paths and instances for external dependency libraries like highlight.js.

```typescript
import { config } from 'md-editor-rt';

config({
  editorExtensions: { highlight: { js: 'https://xxx.cc' } }
});
```

```typescript
export interface EditorExtensions {
  highlight?: {
    instance?: any;
    js?: string;
    css?: {
      [key: string]: {
        light: string;
        dark: string;
      };
    };
  };
  prettier?: {
    // >= 2.2.0
    prettierInstance?: any;
    parserMarkdownInstance?: any;

    standaloneJs?: string;
    parserMarkdownJs?: string;
  };
  cropper?: {
    instance?: any;
    js?: string;
    css?: string;
  };
  screenfull?: {
    instance?: any;
    js?: string;
  };
  mermaid?: {
    instance?: any;
    js?: string;
    // >=5.4.0, Whether to allow zooming to view mermaid modules
    enableZoom?: boolean;
  };
  katex?: {
    instance?: any;
    js?: string;
    css?: string;
  };
}
```

--------------------------------

### Implement a custom DropdownToolbar

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Demonstrates how to create a custom toolbar component using DropdownToolbar and integrate it into the MdEditor via the defToolbars prop.

```jsx
import { useCallback, useState } from 'react';
import { MdEditor, DropdownToolbar } from 'md-editor-rt';
import 'md-editor-rt/lib/style.css';

/**
 * `insert` will be automatically injected into the component by the editor
 */
const MyToolbar = ({ insert = () => {} }) => {
  const [visible, setVisible] = useState(false);

  const onClick = useCallback(() => {
    insert((selectedText) => {
      /**
       * targetValue    Content to be inserted
       * select         Automatically select content, default: true
       * deviationStart Start position of the selected content, default: 0
       * deviationEnd   End position of the selected content, default: 0
       */
      return {
        targetValue: `==${selectedText}==`,
        select: true,
        deviationStart: 0,
        deviationEnd: 0
      };
    });
  }, [insert]);

  return (
    <DropdownToolbar
      visible={visible}
      onChange={setVisible}
      overlay={
        <ul>
          <li onClick={onClick}>option 1</li>
          <li>option 2</li>
        </ul>
      }
      key="emoji-toolbar"
    >
      <svg className="md-editor-icon" aria-hidden="true">
        <use xlinkHref="#icon-emoji"></use>
      </svg>
    </DropdownToolbar>
  );
};

const toolbars = ['bold', 0, '=', 'github'];
const defToolbars = [<MyToolbar key="key" />];

export default () => {
  const [value, setValue] = useState('');

  return <MdEditor modelValue={value} id="md-prev" toolbars={toolbars} defToolbars={defToolbars} onChange={setValue} />;
};
```

--------------------------------

### Custom Header and Footer Toolbar Implementation

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Demonstrates how to define custom components for the header and footer toolbars and pass them to the MdEditor via defToolbars and defFooters.

```jsx
const HeaderTool = (props) => {
  console.log('==', props);
  // == { insert: (...)=> {...}, theme: 'light', ... }

  return <NormalToolbar>Content</NormalToolbar>;
};

const toolbars = [0];
const defToolbars = [<HeaderTool key="key" />];

const MyEditor1 = () => {
  return <MdEditor toolbars={toolbars} defToolbars={defToolbars} />;
};

// ===================================

const FooterTool = (props) => {
  console.log('==', props);
  // == { theme: 'light', disabled: false, language: 'zh-CN' }

  return <NormalFooterToolbar>Content</NormalFooterToolbar>;
};

const footers = [0];
const defFooters = [<FooterTool key="key" />];

const MyEditor2 = () => {
  return <MdEditor footers={footers} defFooters={defFooters} />;
};
```

--------------------------------

### Implement NormalFooterToolbar

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Shows how to define and register a custom footer toolbar component using NormalFooterToolbar.

```jsx
import { MdEditor, NormalFooterToolbar } from 'md-editor-rt';

const FooterTool = (props) => {
  return <NormalFooterToolbar>Content</NormalFooterToolbar>;
};

const footers = [0];
const defFooters = [<FooterTool key="key" />];

export default () => {
  return <MdEditor footers={footers} defFooters={defFooters} />;
};
```

--------------------------------

### Configure Code Highlight Themes

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Register custom highlight.js themes via the config function and apply them using the codeTheme prop.

```js
import { config } from 'md-editor-rt';

config({
  editorExtensions: {
    highlight: {
      css: {
        atom: {
          light: 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/styles/atom-one-light.min.css',
          dark: 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/styles/atom-one-dark.min.css'
        },
        xxx: {
          light: 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/styles/xxx-light.css',
          dark: 'https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.5.1/styles/xxx-dark.css'
        }
      }
    }
  }
});
```

```jsx
<MdEditor codeTheme="xxx" />
```

--------------------------------

### previewComponent

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Inject a custom component for the preview area.

```APIDOC
## previewComponent

### Description
Allows full control over the rendering of the preview area by injecting a custom component. The component receives `html`, `id`, and `className` as props.
```

--------------------------------

### Configure katexConfig

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Customize the katex configuration by providing a function that receives the base configuration and returns the modified object.

```javascript
import { config } from 'md-editor-rt';

config({
  katexConfig(base: any) {
    return {
      ...base,
      strict: false,
    };
  },
});
```

--------------------------------

### Set Editor Theme

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Configure the editor's visual theme using the theme prop.

```jsx
<MdEditor theme="dark" />
```

--------------------------------

### focus(option)

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Focus on the textarea.

```APIDOC
## focus(option)

### Description
Sets focus on the editor's textarea. The optional parameter defines the cursor position.
```

--------------------------------

### Implement MdCatalog for Markdown Preview

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Shows how to link an MdCatalog component to an MdPreview instance using a shared editorId.

```jsx
import { MdPreview, MdCatalog } from 'md-editor-rt';
import 'md-editor-rt/lib/preview.css';

const editorId = 'my-editor';

export default () => {
  const [state] = useState({
    text: '# heading',
    scrollElement: document.documentElement
  });

  return (
    <>
      {/* Ensure that the editorId is the same */}
      <MdPreview id={editorId} modelValue={state.text} />
      <MdCatalog editorId={editorId} scrollElement={state.scrollElement} />
    </>
  );
};
```

--------------------------------

### config(option: GlobalConfig)

Source: https://imzbf.github.io/md-editor-rt/en-US/api

The config function is used to reconfigure markdown-it and other editor settings. It is recommended to call this at the project entry point.

```APIDOC
## config(option: GlobalConfig)

### Description
Reconfigures the editor settings, including CodeMirror extensions, markdown-it configurations, and plugins.

### Parameters
- **option** (GlobalConfig) - Required - Configuration object containing settings for codeMirrorExtensions, markdownItConfig, and markdownItPlugins.
```

--------------------------------

### Configure Toolbar Items

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Define the order and visibility of toolbar buttons, using '-' for separators and '=' to divide left and right sections.

```javascript
[
  'bold',
  'underline',
  'italic',
  '-',
  'strikeThrough',
  'sub',
  'sup',
  'quote',
  'unorderedList',
  'orderedList',
  'task',
  '-',
  'codeRow',
  'code',
  'link',
  'image',
  'table',
  'mermaid',
  'katex',
  '-',
  'revoke',
  'next',
  'save',
  '=',
  'pageFullscreen',
  'fullscreen',
  'preview',
  'previewOnly',
  'htmlPreview',
  'catalog',
  'github'
];
```

--------------------------------

### execCommand(command)

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Insert content into the editor via trigger.

```APIDOC
## execCommand(command)

### Description
Executes a specific editor command (e.g., 'bold') to modify content.
```

--------------------------------

### Configure Mermaid Templates

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Set custom templates for various Mermaid diagram types using mermaidTemplate.

```javascript
import { config } from 'md-editor-rt';

config({
  editorConfig: {
    // mermaid template
    mermaidTemplate: {
      flow: `flow tempalte`,
      sequence: `sequence template`,
      gantt: `gantt template`,
      class: `class template`,
      state: `state template`,
      pie: `pie template`,
      relationship: `relationship template`,
      journey: `journey template`
    }
  }
});
```

--------------------------------

### Implement ModalToolbar in MdEditor

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Demonstrates how to create a custom toolbar component using ModalToolbar and integrate it into the MdEditor component.

```jsx
import { useState } from 'react';
import { MdEditor, ModalToolbar } from 'md-editor-rt';
import 'md-editor-rt/lib/style.css';

/**
 * `insert` will be automatically injected into the component by the editor
 */
const MyToolbar = ({ insert = () => {} }) => {
  const [visible, setVisible] = useState(false);
  const [isFullscreen, setIsFullscreen] = useState(false);

  const onClick = useCallback(() => {
    setVisible(true);
  }, []);

  const onClose = useCallback(() => {
    setVisible(false);
  }, []);

  const onAdjust = useCallback(() => {
    setIsFullscreen((i) => !i);
  }, []);

  const insertHandler = useCallback(() => {
    insert((selectedText) => {
      /**
       * targetValue    Content to be inserted
       * select         Automatically select content, default: true
       * deviationStart Start position of the selected content, default: 0
       * deviationEnd   End position of the selected content, default: 0
       */
      return {
        targetValue: `==${selectedText}==`,
        select: true,
        deviationStart: 0,
        deviationEnd: 0
      };
    });
  }, [insert]);

  return (
    <ModalToolbar
      visible={visible}
      isFullscreen={isFullscreen}
      showAdjust
      title="hover-title"
      modalTitle="modalTitle"
      width="870px"
      height="600px"
      onClick={onClick}
      onClose={onClose}
      onAdjust={onAdjust}
      trigger={
        <svg className="md-editor-icon" aria-hidden="true">
          <use xlinkHref="#icon-read"></use>
        </svg>
      }
    >
      <div
        style={{
          height: '100%',
          padding: '20px',
          overflow: 'auto'
        }}
      >
        <button onClick={insertHandler}>click me</button>
      </div>
    </ModalToolbar>
  );
};

const toolbars = ['bold', 0, '=', 'github'];
const defToolbars = [<MyToolbar key="key" />];

export default () => {
  const [value, setValue] = useState('');
  return <MdEditor modelValue={value} id="md-prev" toolbars={toolbars} defToolbars={defToolbars} onChange={setValue} />;
};
```

--------------------------------

### completions

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Configures additional completion sources for the editor.

```APIDOC
## completions

### Description
Additional completion sources for the editor.

### Type
Array<CompletionSource>

### Default
[]
```

--------------------------------

### Listen to Editor State Changes

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Use the on method to subscribe to internal editor state changes.

```js
editorRef.current?.on('pageFullscreen', (status) => console.log(status));
```

```js
editorRef.current?.on('fullscreen', (status) => console.log(status));
```

```js
editorRef.current?.on('preview', (status) => console.log(status));
```

```js
editorRef.current?.on('previewOnly', (status) => console.log(status));
```

```js
editorRef.current?.on('htmlPreview', (status) => console.log(status));
```

```js
editorRef.current?.on('catalog', (status) => console.log(status));
```

--------------------------------

### config(options)

Source: https://imzbf.github.io/md-editor-rt/en-US/api

The config function is used to globally configure the editor settings and extensions.

```APIDOC
## config(options)

### Description
Configures the editor behavior, including language localization, mermaid templates, rendering performance, and external library dependencies.

### Parameters
- **options** (Object) - Required - Configuration object containing `editorConfig` and `editorExtensions`.

### Usage Example
```javascript
import { config } from 'md-editor-rt';

config({
  editorConfig: {
    renderDelay: 0,
    zIndex: 2000
  },
  editorExtensions: {
    highlight: { js: 'https://example.com/highlight.js' }
  }
});
```
```

--------------------------------

### Implement MdModal with DropdownToolbar

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Demonstrates using MdModal within a custom DropdownToolbar component to display modal content.

```jsx
import { useState } from 'react';
import { MdEditor, DropdownToolbar, MdModal } from 'md-editor-rt';
import 'md-editor-rt/lib/style.css';

/**
 * `insert` will be automatically injected into the component by the editor
 */
const MyToolbar = () => {
  const [visible, setVisible] = useState(false);
  const [mVisible, setMvisible] = useState(false);

  const onClick = useCallback(() => {
    setMvisible(true);
  }, []);

  const onClose = useCallback(() => {
    setMvisible(false);
  }, []);

  return (
    <>
      <DropdownToolbar
        visible={visible}
        onChange={setVisible}
        overlay={
          <ul>
            <li onClick={onClick}>option 1</li>
            <li>option 2</li>
          </ul>
        }
        key="emoji-toolbar"
      >
        <svg className="md-editor-icon" aria-hidden="true">
          <use xlinkHref="#icon-emoji"></use>
        </svg>
      </DropdownToolbar>
      <MdModal title="title" visible={mVisible} onClose={onClose}>
        Content, Content
      </MdModal>
    </>
  );
};

const defToolbars = [<MyToolbar key="key" />];

export default () => {
  const [value, setValue] = useState('');

  return (
    <MdEditor
      modelValue={value}
      id="md-prev"
      toolbars={['bold', 0, '=', 'github']}
      defToolbars={defToolbars}
      onChange={setValue}
    />
  );
};
```

--------------------------------

### Implement Custom Toolbar Items

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Use defToolbars to inject custom components into the toolbar, referencing them by index in the toolbars array.

```jsx
import { MdEditor, NormalToolbar } from 'md-editor-rt';
import 'md-editor-rt/lib/style.css';

const handler = () => {
  console.log('NormalToolbar clicked!');
};

const toolbars = ['github', '=', 0];

const defToolbars = [
  <NormalToolbar
    title="mark"
    onClick={handler}
    trigger={
      <svg className="md-editor-icon" aria-hidden="true">
        <use xlinkHref="#icon-mark"></use>
      </svg>
    }
  />
];

export default () => {
  return <MdEditor modelValue="" toolbars={toolbars} defToolbars={defToolbars} />;
};
```

--------------------------------

### config({ editorExtensionsAttrs })

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Synchronously add attributes to the CDN link tags for editor extensions. Note that src, onload, id, rel, href, and id attributes are managed by the system and should not be overridden.

```APIDOC
## config({ editorExtensionsAttrs })

### Description
Synchronously add attributes to the CDN link tags, consistent with the type of `editorExtensions`.

### Usage
```javascript
import { config } from 'md-editor-rt';

config({
  editorExtensionsAttrs: {
    highlight: {
      js: {
        className: 'hglh-js'
      }
    }
  }
});
```
```

--------------------------------

### insert(callback)

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Manually insert content into the textarea.

```APIDOC
## insert(callback)

### Description
Allows manual insertion of content into the editor's textarea via a callback function that returns insertion details.
```

--------------------------------

### Configure custom completion sources

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Use the completions property to define custom autocomplete logic for the editor. Requires importing CompletionSource from @codemirror/autocomplete.

```tsx
import { useMemo, useState } from 'react';
import { CompletionSource } from '@codemirror/autocomplete';
import { MdEditor } from 'md-editor-rt';
import 'md-editor-rt/lib/style.css';

export default () => {
  const [t, s] = useState('');

  const completions = useMemo<Array<CompletionSource>>(() => {
    return [
      (context) => {
        const word = context.matchBefore(/@\w*/);

        if (word === null || (word.from == word.to && context.explicit)) {
          return null;
        }

        return {
          from: word.from,
          options: [
            {
              label: '@imzbf',
              type: 'text'
            }
          ]
        };
      }
    ];
  }, []);

  return <MdEditor modelValue={t} onChange={s} completions={completions} />;
};
```

--------------------------------

### onGetCatalog

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Triggered to retrieve the article catalogue.

```APIDOC
## onGetCatalog

### Description
Triggered to retrieve the article catalogue.

### Signature
`(list: HeadList[]) => void`
```

--------------------------------

### Custom Toolbar with Text Insertion

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Shows how to use NormalToolbar to create a custom button that inserts formatted text into the editor.

```jsx
import { useCallback, useState } from 'react';
import { MdEditor, NormalToolbar } from 'md-editor-rt';
import 'md-editor-rt/lib/style.css';

/**
 * `insert` will be automatically injected into the component by the editor
 */
const MyToolbar = ({ insert = () => {} }) => {
  const onClick = useCallback(() => {
    insert((selectedText) => {
      /**
       * targetValue    Content to be inserted
       * select         Automatically select content, default: true
       * deviationStart Start position of the selected content, default: 0
       * deviationEnd   End position of the selected content, default: 0
       */
      return {
        targetValue: `==${selectedText}==`,
        select: true,
        deviationStart: 0,
        deviationEnd: 0
      };
    });
  }, [insert]);

  return (
    <NormalToolbar title="mark" onClick={onClick} key="mark-toolbar">
      <svg className="md-editor-icon" aria-hidden="true">
        <use xlinkHref="#icon-mark"></use>
      </svg>
    </NormalToolbar>
  );
};

const toolbars = ['bold', 0, '=', 'github'];
const defToolbars = [<MyToolbar />];

export default () => {
  const [value, setValue] = useState('');

  return <MdEditor modelValue={value} id="md-prev" toolbars={toolbars} defToolbars={defToolbars} onChange={setValue} />;
};
```

--------------------------------

### Set Table Dimensions

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Configure the default table size using the tableShape prop.

```jsx
const tableShape = [8, 4];

() => <MdEditor tableShape={tableShape}>
```

--------------------------------

### togglePreview(status)

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Toggle status of preview.

```APIDOC
## togglePreview(status)

### Description
Toggle the visibility of the preview pane. If no parameter is provided, it switches to the opposite status.
```

--------------------------------

### rerender()

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Re-render the content.

```APIDOC
## rerender()

### Description
Forces a re-render of the editor content.
```

--------------------------------

### Execute Editor Commands

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Trigger editor commands like formatting via string identifiers.

```js
editorRef.current?.execCommand('bold');
```

--------------------------------

### Insert Content into Editor

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Manually inject content into the editor textarea using a callback.

```js
/**
 * @params selectedText
 */
editorRef.current?.insert((selectedText) => {
  /**
   * @return targetValue    Content to be inserted
   * @return select         Automatically select content, default: true
   * @return deviationStart Start position of the selected content, default: 0
   * @return deviationEnd   End position of the selected content, default: 0
   */
  return {
    targetValue: `${selectedText}`,
    select: true,
    deviationStart: 0,
    deviationEnd: 0
  };
});
```

--------------------------------

### Set Markdown Content

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Use the value prop to pass the markdown content to the editor.

```jsx
<MdEditor value="xxx" />
```

--------------------------------

### Configure mermaidConfig

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Customize the mermaid configuration by providing a function that receives the base configuration and returns the modified object.

```javascript
import { config } from 'md-editor-rt';
config({
  mermaidConfig(base: any) {
    return {
      ...base,
      logLevel: 'error',
    };
  },
});
```

--------------------------------

### showToolbarName

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Determines whether to show the toolbar name.

```APIDOC
## showToolbarName

### Description
Show toolbar name or not.

### Type
boolean

### Default
false
```

--------------------------------

### onError

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Captures execution errors such as Cropper, fullscreen, prettier, overlength, or mermaid rendering issues.

```APIDOC
## onError

### Description
Captures execution errors such as Cropper, fullscreen, prettier, overlength, or mermaid rendering issues.

### Signature
`(err: InnerError) => void`
```

--------------------------------

### NormalFooterToolbar

Source: https://imzbf.github.io/md-editor-rt/en-US/api

A component for creating custom footer toolbar items.

```APIDOC
## NormalFooterToolbar

### Description
A component used to define custom footer toolbar items.

### Events
- **onClick** ((e: MouseEvent) => void) - Optional - Triggered when the toolbar is clicked.

### Slots
- **children** (ReactNode) - Required - The content to display within the footer toolbar.
```

--------------------------------

### onInput

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Triggered when the element receives input.

```APIDOC
## onInput

### Description
Triggered when the element receives input.

### Signature
`(event: Event) => void`
```

--------------------------------

### codeStyleReverse

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Configuration for reversing code block themes.

```APIDOC
## codeStyleReverse

### Description
When enabled, the code style will be reversed to dark if the theme's code block has a dark background.

### Type
`boolean`

### Default
`true`
```

--------------------------------

### catalogLayout

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Sets the layout style for the built-in catalog.

```APIDOC
## catalogLayout

### Description
>=5.3.0, the built-in catalog status: 'fixed' - floats above the content; 'flat' - displays on the right side.

### Type
'fixed' | 'flat'

### Default
fixed
```

--------------------------------

### togglePreviewOnly(status)

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Toggle into Preview Only Mode.

```APIDOC
## togglePreviewOnly(status)

### Description
Toggle the editor into Preview Only mode. If no parameter is provided, it switches to the opposite status.
```

--------------------------------

### onRemount

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Triggered when content is re-mounted, useful for retrieving nodes within the content (>=5.3.0).

```APIDOC
## onRemount

### Description
Triggered when content is re-mounted, useful for retrieving nodes within the content (>=5.3.0).

### Signature
`() => void`
```

--------------------------------

### domEventHandlers(handlers)

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Supports listening to all DOM events.

```APIDOC
## domEventHandlers(handlers)

### Description
Registers custom handlers for DOM events within the editor.
```

--------------------------------

### onFocus

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Triggered when the textarea receives focus.

```APIDOC
## onFocus

### Description
Triggered when the textarea receives focus.

### Signature
`(event: FocusEvent<HTMLTextAreaElement, Element>) => void`
```

--------------------------------

### toggleFullscreen(status)

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Toggle status of fullscreen within the browser.

```APIDOC
## toggleFullscreen(status)

### Description
Toggle the browser-level fullscreen status. If no parameter is provided, it switches to the opposite status.
```

--------------------------------

### Handle Image Upload in MdEditor

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Processes file uploads and requires a callback to update the editor with image URLs. The modal remains open until the callback is invoked.

```jsx
import React, { useState } from 'react';
import { MdEditor } from 'md-editor-rt';
import 'md-editor-rt/lib/style.css';

const onUploadImg = async (files, callback) => {
  const res = await Promise.all(
    files.map((file) => {
      return new Promise((rev, rej) => {
        const form = new FormData();
        form.append('file', file);

        axios
          .post('/api/img/upload', form, {
            headers: {
              'Content-Type': 'multipart/form-data'
            }
          })
          .then((res) => rev(res))
          .catch((error) => rej(error));
      });
    })
  );

  // Approach 1
  callback(res.map((item) => item.data.url));
  // Approach 2
  // callback(
  //   res.map((item: any) => ({
  //     url: item.data.url,
  //     alt: 'alt',
  //     title: 'title'
  //   }))
  // );
};

export default () => {
  const [text, setText] = useState('# Hello Editor');

  return <MdEditor modelValue={text} onChange={setText} onUploadImg={onUploadImg} />;
};
```

--------------------------------

### Customize Editor Icons

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Override default editor icons by providing a CustomIcon object. Note that 'copy' and 'collapse-tips' icons must be strings.

```tsx
import React from 'react';
import type { CustomIcon } from 'md-editor-rt';
import { MdEditor, StrIcon } from 'md-editor-rt';
// Assuming you have installed an icon library or customized icon components
import { IconFont } from 'tdesign-icons-react';
import 'md-editor-rt/lib/style.css';

const customIcon: CustomIcon = {
  bold: {
    component: 'A'
  },
  // Demonstrating the use of default icons
  copy: StrIcon('copy', {}),
  // copy: '<i class="fa fa-car"></i>',
  // 'collapse-tips': '<i class="fa fa-car"></i>',
  preview: {
    component: '<i class="fa fa-car"></i>'
  },
  github: {
    component: IconFont,
    props: {
      name: 'sneer'
    }
  }
};

export default () => {
  return <MdEditor modelValue="" customIcon={customIcon} />;
};
```

```ts
type IconName =
  | 'bold'
  | 'underline'
  | 'italic'
  | 'strike-through'
  | 'title'
  | 'sub'
  | 'sup'
  | 'quote'
  | 'unordered-list'
  | 'ordered-list'
  | 'task'
  | 'code-row'
  | 'code'
  | 'link'
  | 'image'
  | 'table'
  | 'revoke'
  | 'next'
  | 'save'
  | 'prettier'
  | 'minimize'
  | 'maximize'
  | 'fullscreen-exit'
  | 'fullscreen'
  | 'preview-only'
  | 'preview'
  | 'preview-html'
  | 'catalog'
  | 'github'
  | 'mermaid'
  | 'formula'
  | 'close'
  | 'delete'
  | 'upload';

type CustomIcon = {
  [key in IconName]?: {
    component: Component | JSX.Element | string;
    props: {
      [key: string | number | symbol]: any;
    };
  };
} & {
  copy?: string;
  'collapse-tips'?: string;
};
```

--------------------------------

### onUploadImg

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Triggered when uploading images. The modal remains open until the callback is invoked with the image URLs.

```APIDOC
## onUploadImg

### Description
Triggered when uploading images. The modal remains open until the callback is invoked with the image URLs.

### Signature
`(files: Array<File>, callback: (urls: string[] | { url: string; alt: string; title: string }[]) => void) => void`
```

--------------------------------

### Inject Custom Preview Component

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Use the previewComponent prop to fully control the rendering of the preview area. Ensure the provided id and className are applied to the container element.

```tsx
import { MdEditor } from 'md-editor-rt';
const CustomPreview = ({ html, id, className }) => {
  return <div id={id} className={className} dangerouslySetInnerHTML={{ __html: html }} />;
};
export default () => {
  return <MdEditor previewComponent={CustomPreview} />;
};
```

--------------------------------

### inputBoxWidth

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Sets the default width of the input box.

```APIDOC
## inputBoxWidth

### Description
Default width of input box.

### Type
string

### Default
50%
```

--------------------------------

### onChange

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Triggered when the content changes, bound to the textarea oninput event.

```APIDOC
## onChange

### Description
Triggered when the content changes, bound to the textarea oninput event.

### Signature
`(v: string) => void`
```

--------------------------------

### toggleCatalog(status)

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Toggle status of catalog.

```APIDOC
## toggleCatalog(status)

### Description
Toggle the visibility of the document catalog. If no parameter is provided, it switches to the opposite status.
```

--------------------------------

### togglePageFullscreen(status)

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Toggle status of fullscreen within the page.

```APIDOC
## togglePageFullscreen(status)

### Description
Toggle the fullscreen status within the page container. If no parameter is provided, it switches to the opposite status.
```

--------------------------------

### customIcon

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Allows customization of editor icons.

```APIDOC
## customIcon

### Description
Provides a way to replace default editor icons with custom components or strings.

### Type
`CustomIcon`

### Default
`{}`
```

--------------------------------

### Define MarkdownItConfig Type

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Defines the signature for the function used to customize markdown-it instances.

```typescript
type MarkdownItConfig = (
  md: markdownit,
  options: {
    editorId: string;
  }
) => void;
```

--------------------------------

### MdEditor Component Props

Source: https://imzbf.github.io/md-editor-rt/en-US/api

A collection of configuration properties for the MdEditor component.

```APIDOC
## MdEditor Props

### pageFullscreen
- **Type**: boolean
- **Default**: false
- **Description**: Enables full-screen mode within the web page.

### preview
- **Type**: boolean
- **Default**: true
- **Description**: Toggles the preview content pane in the editor.

### htmlPreview
- **Type**: boolean
- **Default**: false
- **Description**: Enables HTML preview mode. Set `preview` to `false` when this is `true`.

### toolbars
- **Type**: Array
- **Default**: [all]
- **Description**: Defines the visible toolbar items. Items can be sorted, split by '-', and divided into left/right sections using '='.

### toolbarsExclude
- **Type**: Array
- **Default**: []
- **Description**: Specifies toolbar items to hide.

### floatingToolbars
- **Type**: Array
- **Default**: []
- **Description**: Defines the contents of the floating toolbar.

### defToolbars
- **Type**: Array<VNode>
- **Default**: []
- **Description**: Custom toolbar components. Display them by adding their index to the `toolbars` prop.

### noPrettier
- **Type**: boolean
- **Default**: true
- **Description**: Toggles the use of Prettier for content beautification.

### tabWidth
- **Type**: number
- **Default**: 2
- **Description**: Sets the number of spaces per tab.

### tableShape
- **Type**: [number, number] | [number, number, number, number]
- **Default**: [6, 4]
- **Description**: Presets the table size as [columns, rows, maxColumns, maxRows].

### placeholder
- **Type**: string
- **Default**: ''
- **Description**: Placeholder text for the editor.

### footers
- **Type**: Array<'markdownTotal' | '=' | 'scrollSwitch' | number>
- **Default**: ['markdownTotal', '=', 'scrollSwitch']
- **Description**: Configures footer content, divided by '='.

### defFooters
- **Type**: Array<ReactNode>
- **Default**: []
- **Description**: Custom footer components.

### scrollAuto
- **Type**: boolean
- **Default**: true
- **Description**: Default scroll behavior setting.

### noUploadImg
- **Type**: boolean
- **Default**: false
- **Description**: Hides the image upload button.

### autoFocus
- **Type**: boolean
- **Default**: false
- **Description**: Automatically focuses the editor on load.

### disabled
- **Type**: boolean
- **Default**: false
- **Description**: Disables the editor.

### readOnly
- **Type**: boolean
- **Default**: false
- **Description**: Sets the editor to read-only mode.

### maxLength
- **Type**: number
- **Default**: null
- **Description**: Sets the maximum character length for the editor.

### autoDetectCode
- **Type**: boolean
- **Default**: false
- **Description**: Automatically detects the language of code pasted from VS Code.
```

--------------------------------

### MdCatalog Component

Source: https://imzbf.github.io/md-editor-rt/en-US/api

A component for generating and navigating a table of contents for markdown content.

```APIDOC
## MdCatalog

### Description
A component that generates a catalog (table of contents) based on markdown headings.

### Props
- **editorId** (string) - Required - The editor's ID used to register listening events.
- **className** (string) - Optional - CSS class name.
- **mdHeadingId** (mdHeadingId) - Optional - Heading ID configuration.
- **scrollElement** (string | HTMLElement) - Optional - Selector or element for the scroll container.
- **theme** ('light' | 'dark') - Optional - Theme of the catalog.
- **offsetTop** (number) - Optional - Pixels from top to highlight current item, default 20.
- **scrollElementOffsetTop** (number) - Optional - OffsetTop of the scroll container, default 0.
- **catalogMaxDepth** (number) - Optional - Maximum depth of the catalog to display.

### Events
- **onClick** ((e: MouseEvent, t: TocItem) => void) - Optional - Triggered when a catalog item is clicked.
- **onActive** ((heading: HeadList | undefined) => void) - Optional - Triggered when a heading is highlighted.
```

--------------------------------

### onSave

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Triggered when saving content via ctrl+s or the save button.

```APIDOC
## onSave

### Description
Triggered when saving content via ctrl+s or the save button.

### Signature
`(v: string, h: Promise<string>) => void`
```

--------------------------------

### Set Rendering Delay

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Adjust the renderDelay in milliseconds to control the timing of editor rendering.

```javascript
import { config } from 'md-editor-rt';

config({
  editorConfig: {
    // delay rendering time(ms)
    renderDelay: 0
  }
});
```

--------------------------------

### Configure editorExtensionsAttrs

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Use this to add custom attributes to CDN link tags. Do not override src, onload, id, rel, or href attributes as they are managed by the editor.

```javascript
import { config } from 'md-editor-rt';

config({
  editorExtensionsAttrs: {
    highlight: {
      js: {
        className: 'hglh-js'
      },
      css: {
        atom: {
          light: {
            className: 'atom-light-css'
          },
          dark: {
            className: 'atom-dark-css'
          }
        }
      }
    }
  }
});
```

```javascript
import { config, editorExtensionsAttrs } from 'md-editor-rt';

config({
  editorExtensionsAttrs
});
```

--------------------------------

### noImgZoomIn

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Controls image enlargement functionality.

```APIDOC
## noImgZoomIn

### Description
Enables or disables the function of enlarging images when clicked.

### Type
`boolean`

### Default
`false`
```

--------------------------------

### Toggle Editor Display Modes

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Methods to toggle various UI states of the editor.

```js
editorRef.current?.togglePageFullscreen(true);
```

```js
editorRef.current?.toggleFullscreen(true);
```

```js
editorRef.current?.togglePreview(true);
```

```js
editorRef.current?.togglePreviewOnly(true);
```

```js
editorRef.current?.toggleHtmlPreview(true);
```

```js
editorRef.current?.toggleCatalog(true);
```

--------------------------------

### Rerender Editor

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Force a re-render of the editor content.

```js
editorRef.current?.rerender();
```

--------------------------------

### Handle DOM Events

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Attach listeners to internal DOM events.

```js
editorRef.current?.domEventHandlers({
  compositionstart: () => {
    console.log('compositionstart');
  }
});
```

--------------------------------

### ModalToolbar Component

Source: https://imzbf.github.io/md-editor-rt/en-US/api

A component for creating custom modal-based toolbars within the editor.

```APIDOC
## ModalToolbar

### Description
A component that provides a toolbar button which opens a modal window when clicked.

### Props
- **title** (string) - Optional - Title of the toolbar.
- **modalTitle** (ReactNode) - Optional - Title of the Modal.
- **visible** (boolean) - Required - Visibility of Modal.
- **width** (string) - Optional - Width of Modal, default 'auto'.
- **height** (string) - Optional - Height of Modal, default 'auto'.
- **showAdjust** (boolean) - Optional - Visibility of fullscreen button.
- **isFullscreen** (boolean) - Required if showAdjust is true - Status of fullscreen.
- **trigger** (ReactNode) - Required - Icon or element displayed on the toolbar.
- **children** (ReactNode) - Required - Content of the Modal.
- **className** (string) - Optional - CSS class name.
- **style** (CSSProperties) - Optional - Inline styles.
- **showMask** (boolean) - Optional - Whether to display the mask layer, default true.

### Events
- **onClick** (() => void) - Required - Triggered when the toolbar button is clicked.
- **onClose** (() => void) - Required - Triggered when the modal is closed.
- **onAdjust** ((val: boolean) => void) - Optional - Triggered when the fullscreen button is clicked.
```

--------------------------------

### Define Custom Language Strings

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Use languageUserDefined to override or add localization strings for the editor interface.

```javascript
import { config } from 'md-editor-rt';

config({
  editorConfig: {
    languageUserDefined: {
      'en-US': {
        toolbarTips: {
          bold: 'bold',
          underline: 'underline',
          italic: 'italic',
          strikeThrough: 'strikeThrough',
          title: 'title',
          sub: 'subscript',
          sup: 'superscript',
          quote: 'quote',
          unorderedList: 'unordered list',
          orderedList: 'ordered list',
          codeRow: 'inline code',
          code: 'block-level code',
          link: 'link',
          image: 'image',
          table: 'table',
          mermaid: 'mermaid',
          katex: 'formula',
          revoke: 'revoke',
          next: 'undo revoke',
          save: 'save',
          prettier: 'prettier',
          pageFullscreen: 'fullscreen in page',
          fullscreen: 'fullscreen',
          preview: 'preview',
          previewOnly: 'previewOnly',
          htmlPreview: 'html preview',
          catalog: 'catalog',
          github: 'source code'
        },
        titleItem: {
          h1: 'Lv1 Heading',
          h2: 'Lv2 Heading',
          h3: 'Lv3 Heading',
          h4: 'Lv4 Heading',
          h5: 'Lv5 Heading',
          h6: 'Lv6 Heading'
        },
        imgTitleItem: {
          link: 'Add Img Link',
          upload: 'Upload Img',
          clip2upload: 'Clip Upload'
        },
        linkModalTips: {
          linkTitle: 'Add Link',
          imageTitle: 'Add Image',
          descLabel: 'Desc:',
          descLabelPlaceHolder: 'Enter a description...',
          urlLabel: 'Link:',
          urlLabelPlaceHolder: 'Enter a link...',
          buttonOK: 'OK'
        },
        clipModalTips: {
          title: 'Crop Image',
          buttonUpload: 'Upload'
        },
        copyCode: {
          text: 'Copy',
          successTips: 'Copied!',
          failTips: 'Copy failed!'
        },
        mermaid: {
          flow: 'flow',
          sequence: 'sequence',
          gantt: 'gantt',
          class: 'class',
          state: 'state',
          pie: 'pie',
          relationship: 'relationship',
          journey: 'journey'
        },
        katex: {
          inline: 'inline',
          block: 'block'
        },
        footer: {
          markdownTotal: 'Word Count',
          scrollAuto: 'Scroll Auto'
        }
      }
    }
  }
});
```

--------------------------------

### DropdownToolbar Component

Source: https://imzbf.github.io/md-editor-rt/en-US/api

The DropdownToolbar component provides a way to render a dropdown menu within the editor toolbar. It requires a visibility state and an overlay component to display.

```APIDOC
## DropdownToolbar

### Description
A component for creating custom dropdown menus in the md-editor-rt toolbar.

### Props
- **title** (string) - Optional - Title of the toolbar.
- **visible** (boolean) - Required - Controls the visibility of the dropdown.
- **children** (ReactNode) - Optional - The icon or element displayed on the toolbar.
- **overlay** (ReactNode) - Required - The content to be displayed inside the dropdown box.

### Events
- **onChange** (function) - Required - Callback function triggered when visibility changes: `(visible: boolean) => void`.
```

--------------------------------

### toggleHtmlPreview(status)

Source: https://imzbf.github.io/md-editor-rt/en-US/api

Toggle status of htmlPreview.

```APIDOC
## toggleHtmlPreview(status)

### Description
Toggle the HTML preview mode. If no parameter is provided, it switches to the opposite status.
```
Tokens:
Raw