Skip to content

API_REFERENCE.md

Latest commit

 

History

History
895 lines (651 loc) · 26.6 KB

API_REFERENCE.md

File metadata and controls

895 lines (651 loc) · 26.6 KB

API Reference

Props

autoFocus

If true, focuses the input.

Type Default Value Platform
bool false Both

autoCapitalize

Tells input to automatically capitalize certain characters.

  • characters: all characters.
  • words: first letter of each word.
  • sentences: first letter of each sentence.
  • none: don't auto capitalize anything.
Type Default Value Platform
'none' | 'sentences' | 'words' | 'characters' 'sentences' Both

contextMenuItems

An array of custom items to display in the native text editing menu. Each item specifies a title, visibility flag, and a callback that fires when the item is tapped.

The onPress callback receives a single object argument with the following properties:

  • text - the currently selected text.
  • selection - an object with start and end indices of the current selection.
  • styleState - the latest OnChangeStateEvent payload reflecting active styles at the time of the tap.

Item type:

interface ContextMenuItem {
  text: string;
  onPress: (args: {
    text: string;
    selection: { start: number; end: number };
    styleState: OnChangeStateEvent;
  }) => void;
  visible?: boolean;
}
  • text is the title displayed in the menu.
  • onPress is the callback invoked when the item is tapped.
  • visible controls whether the item is shown. Defaults to true.
Type Default Value Platform
ContextMenuItem[] [] iOS

Note

On iOS items appear in array order, before the system items (Copy/Paste/Cut). On Android, there is no guaranteed order and custom items may be displayed in a submenu, depending on the device manufacturer.

cursorColor

When provided it will set the color of the cursor (or "caret") in the component.

Type Default Value Platform
color system default Android

defaultValue

Provides an initial value for the input. If the string is a valid HTML output of the EnrichedTextInput component (or other HTML that the parser will accept), proper styles will be applied.

Type Default Value Platform
string - Both

editable

If false, text is not editable.

Type Default Value Platform
bool true Both

Note

Setting editable to false will disable all user interactions with the input. However, some programmatic changes (like toggling styles or changing value imperatively) via ref methods will still work.

htmlStyle

A prop for customizing styles appearances.

Type Default Value Platform
HtmlStyle default values from HtmlStyle Both

mentionIndicators

The recognized mention indicators. Each item needs to be a 1 character long string.

Type Default Value Platform
array of string ['@'] Both

linkRegex

A custom regex pattern for detecting links in the input. If not provided, a default regex will be used. With this approach you can customize what patterns should be recognized as links, for example you can make it so that only links starting with https:// are detected, or you can support custom schemes. Keep in mind that not all JS regex features are supported, for example variable-width lookbehinds won't work.

Type Default Value Platform
RegExp default native platform regex Both

Tip

With this approach you can also disable link detection completely by providing a null value as the prop.

onBlur

Callback that's called whenever the input loses focused (is blurred).

Type Platform
() => void Both

onChangeHtml

Callback that is called when input's HTML changes.

Payload interface:

interface OnChangeHtmlEvent {
  value: string;
}
  • value is the new HTML.
Type Platform
(event: NativeSyntheticEvent<OnChangeHtmlEvent>) => void Both

Tip

Specifying onChangeHtml may have performance implications, especially with large documents, as it requires continuous HTML parsing. If you only need the HTML content at specific moments (e.g., when saving), consider using the getHTML ref method instead. When onChangeHtml is not provided, the component optimizes performance by avoiding unnecessary HTML parsing.

onChangeMention

Callback that gets called anytime user makes some changes to a mention that is being edited.

Payload interface:

interface OnChangeMentionEvent {
  indicator: string;
  text: string;
}
  • indicator is the indicator of the currently edited mention.
  • text contains whole text that has been typed after the indicator.
Type Platform
(event: OnChangeMentionEvent) => void Both

onChangeSelection

Callback that is called each time user changes selection or moves the cursor in the input.

Payload interface:

interface OnChangeSelectionEvent {
  start: Int32;
  end: Int32;
  text: string;
}
  • start is the index of the selection's beginning.
  • end is the first index after the selection's ending. For just a cursor in place (no selection), start equals end.
  • text is the input's text in the current selection.
Type Platform
(event: NativeSyntheticEvent<OnChangeSelectionEvent>) => void Both

onChangeState

Callback that gets called when any of the styles within the selection changes.

Payload interface:

interface OnChangeStateEvent {
  bold: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  italic: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  underline: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  strikeThrough: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  inlineCode: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  h1: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  h2: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  h3: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  h4: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  h5: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  h6: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  codeBlock: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  blockQuote: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  orderedList: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  unorderedList: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  link: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  image: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  mention: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
  checkboxList: {
    isActive: boolean;
    isConflicting: boolean;
    isBlocking: boolean;
  };
}
  • isActive indicates if the style is active within current selection.
  • isBlocking indicates if the style is blocked by other currently active, meaning it can't be toggled.
  • isConflicting indicates if the style is in conflict with other currently active styles, meaning toggling it will remove conflicting style.
Type Platform
(event: NativeSyntheticEvent<OnChangeStateEvent>) => void Both

onChangeText

Callback called when any text changes occur in the input.

Payload interface:

interface OnChangeTextEvent {
  value: string;
}
  • value is the new text value of the input.
Type Platform
(event: NativeSyntheticEvent<OnChangeTextEvent>) => void Both

Tip

If you don't need the plain text value do not specify onChangeText, as it may have performance implications due to continuous text extraction.

onEndMention

Callback that is called when the user no longer edits a mention actively - has moved the cursor somewhere else or put a space and the cursor isn't within the edited mention.

  • indicator is the indicator of the mention that was being edited.
Type Platform
(indicator: string) => void Both

onFocus

Callback that's called whenever the input is focused.

Type Platform
() => void Both

onLinkDetected

Callback that gets called when either a new link has been added or the user has moved the cursor/selection to some link.

Payload interface contains all the useful link data:

interface OnLinkDetected {
  text: string;
  url: string;
  start: Int32;
  end: Int32;
}
  • text is the link's displayed text.
  • url is the underlying link's URL.
  • start is the starting index of the link.
  • end is the first index after the ending index of the link.
Type Platform
(event: OnLinkDetected) => void Both

onMentionDetected

Callback called when mention has been detected - either a new mention has been added or the user has moved the cursor/selection to some mention.

Payload interface contains all the useful mention data:

interface OnMentionDetected {
  text: string;
  indicator: string;
  attributes: Record<string, string>;
}
  • text is the mention's displayed text.
  • indicator is the indicator of the mention.
  • attributes are the additional user-defined attributes that are being stored with the mention.
Type Platform
(event: OnMentionDetected) => void Both

onStartMention

Callback that gets called whenever a mention editing starts (after placing the indicator).

  • indicator is the indicator of the mention that begins editing.
Type Platform
(indicator: string) => void Both

onKeyPress

Callback that is called when a key is pressed. See TextInput onKeyPress for more details.

export interface OnKeyPressEvent {
  key: string;
}
Type Platform
(event: NativeSyntheticEvent<OnKeyPressEvent>) => void Both

OnPasteImages

Callback invoked when the user pastes one or more images or GIFs into the input.

  • images - is an array of objects containing the details (URI, MIME type, and dimensions) for each pasted image/GIF.
export interface OnPasteImagesEvent {
  images: {
    uri: string;
    type: string;
    width: Float;
    height: Float;
  }[];
}
Type Platform
(event: NativeSyntheticEvent<OnPasteImagesEvent>) => void Both

placeholder

The placeholder text that is displayed in the input if nothing has been typed yet. Disappears when something is typed.

Type Default Value Platform
string '' Both

placeholderTextColor

Input placeholder's text color.

Type Default Value Platform
color input's color Both

ref

A React ref that lets you call any ref methods on the input.

Type Default Value Platform
RefObject<EnrichedTextInputInstance | null> - Both

selectionColor

Color of the selection rectangle that gets drawn over the selected text. On iOS, the cursor (caret) also gets set to this color.

Type Default Value Platform
color system default Both

style

Accepts most ViewStyle props, but keep in mind that some of them might not be supported.

Additionally following TextStyle props are supported

  • color
  • fontFamily
  • fontSize
  • fontWeight
  • lineHeight
  • fontStyle only on Android
Type Default Value Platform
View Style | Text Style - Both

ViewProps

The input inherits ViewProps, but keep in mind that some of the props may not be supported.

androidExperimentalSynchronousEvents - EXPERIMENTAL

If true, Android will use experimental synchronous events. This will prevent from input flickering when updating component size. However, this is an experimental feature, which has not been thoroughly tested. We may decide to enable it by default in a future release.

Type Default Value Platform
bool false Android

useHtmlNormalizer - EXPERIMENTAL

If true, external HTML pasted/inserted into the input (e.g. from Google Docs, Word, or web pages) will be normalized into the canonical tag subset that the enriched parser understands. However, this is an experimental feature, which has not been thoroughly tested. We may decide to enable it by default in a future release.

Type Default Value Platform
bool false Both

Ref Methods

All the methods should be called on the input's ref.

.blur()

blur: () => void;

Blurs the input.

.focus()

focus: () => void;

Focuses the input.

.getHTML()

getHTML: () => Promise<string>;

Returns a Promise that resolves with the current HTML content of the input. This is useful when you need to get the HTML on-demand (e.g., when saving) without the performance overhead of continuous HTML parsing via onChangeHtml.

.setImage()

setImage: (src: string, width: number, height: number) => void;

Sets the inline image at the current selection.

  • src: string - absolute path to a file or remote image address.
  • width: number - width of the image.
  • height: number - height of the image.

Note

It's developer responsibility to provide proper width and height, which may require calculating aspect ratio. Also, keep in mind that in case of providing incorrect image source, static placeholder will be displayed. We may consider adding automatic image size detection and improved error handling in future releases.

.setLink()

setLink: (
  start: number,
  end: number,
  text: string,
  url: string
) => void;

Sets the link at the given place with a given displayed text and URL. Link will replace any text if there was some between start and end indexes. Setting a link with start equal to end will just insert it in place.

  • start: number - the starting index where the link should be.
  • end: number - first index behind the new link's ending index.
  • text: string - displayed text of the link.
  • url: string - URL of the link.

.removeLink()

removeLink: (start: number, end: number) => void;

Removes link styling from any links found within the given range. The text content is preserved, only the link attributes are stripped. Out-of-bounds values are clamped to valid range.

  • start: number - the starting index of the range to remove links from.
  • end: number - first index behind the range's ending index.

.setMention()

setMention: (
  indicator: string,
  text: string,
  attributes?: Record<string, string>
) => void;

Sets the currently edited mention with a given indicator, displayed text and custom attributes.

  • indicator: string - the indicator of the set mention.
  • text: string - the text that should be displayed for the mention. Anything the user typed gets replaced by that text. The mention indicator isn't added to that text.
  • attributes?: Record<string, string> - additional, custom attributes for the mention that can be passed as a TypeScript record. They are properly preserved through parsing from and to the HTML format.

.setValue()

setValue: (value: string) => void;

Sets the input's value.

  • value: string - value to set, it can either be react-native-enriched supported HTML string or raw text.

.setSelection()

setSelection: (start: number, end: number) => void;

Sets the selection at the given indexes.

  • start: number - starting index of the selection.
  • end: number - first index after the selection's ending index. For just a cursor in place (no selection), start equals end.

.startMention()

startMention: (indicator: string) => void;

Starts a mention with the given indicator. It gets put at the cursor/selection.

  • indicator: string - the indicator that starts the new mention.

.toggleBlockQuote()

toggleBlockQuote: () => void;

Toggles blockquote style at the current selection.

.toggleBold()

toggleBold: () => void;

Toggles bold formatting at the current selection.

.toggleCodeBlock()

toggleCodeBlock: () => void;

Toggles codeblock formatting at the current selection.

.toggleH1()

toggleH1: () => void;

Toggles heading 1 (H1) style at the current selection.

.toggleH2()

toggleH2: () => void;

Toggles heading 2 (H2) style at the current selection.

.toggleH3()

toggleH3: () => void;

Toggles heading 3 (H3) style at the current selection.

.toggleH4()

toggleH4: () => void;

Toggles heading 4 (H4) style at the current selection.

.toggleH5()

toggleH5: () => void;

Toggles heading 5 (H5) style at the current selection.

.toggleH6()

toggleH6: () => void;

Toggles heading 6 (H6) style at the current selection.

.toggleInlineCode()

toggleInlineCode: () => void;

Applies inline code formatting to the current selection.

.toggleItalic()

toggleItalic: () => void;

Toggles italic formatting at the current selection.

.toggleOrderedList()

toggleOrderedList: () => void;

Converts current selection into an ordered list.

.toggleStrikeThrough()

toggleStrikeThrough: () => void;

Applies strikethrough formatting to the current selection.

.toggleUnderline()

toggleUnderline: () => void;

Applies underline formatting to the current selection.

.toggleUnorderedList()

toggleUnorderedList: () => void;

Converts current selection into an unordered list.

.toggleCheckboxList()

toggleCheckboxList: (checked: boolean) => void;

Converts current selection into an unordered list with checkboxes as items. Each checkbox can be either checked or unchecked. User can later toggle each checkbox individually by tapping on it.

  • checked: boolean - defines whether the checkboxes should be checked or unchecked by default.

HtmlStyle type

Allows customizing HTML styles.

interface HtmlStyle {
  h1?: {
    fontSize?: number;
    bold?: boolean;
  };
  h2?: {
    fontSize?: number;
    bold?: boolean;
  };
  h3?: {
    fontSize?: number;
    bold?: boolean;
  };
  h4?: {
    fontSize?: number;
    bold?: boolean;
  };
  h5?: {
    fontSize?: number;
    bold?: boolean;
  };
  h6?: {
    fontSize?: number;
    bold?: boolean;
  };
  blockquote?: {
    borderColor?: ColorValue;
    borderWidth?: number;
    gapWidth?: number;
    color?: ColorValue;
  };
  codeblock?: {
    color?: ColorValue;
    borderRadius?: number;
    backgroundColor?: ColorValue;
  };
  code?: {
    color?: ColorValue;
    backgroundColor?: ColorValue;
  };
  a?: {
    color?: ColorValue;
    textDecorationLine?: 'underline' | 'none';
  };
  mention?: Record<string, MentionStyleProperties> | MentionStyleProperties;
  ol?: {
    gapWidth?: number;
    marginLeft?: number;
    markerFontWeight?: TextStyle['fontWeight'];
    markerColor?: ColorValue;
  };
  ul?: {
    bulletColor?: ColorValue;
    bulletSize?: number;
    marginLeft?: number;
    gapWidth?: number;
  };
  ulCheckbox?: {
    boxColor?: ColorValue;
    boxSize?: number;
    marginLeft?: number;
    gapWidth?: number;
  };
}

interface MentionStyleProperties {
  color?: ColorValue;
  backgroundColor?: ColorValue;
  textDecorationLine?: 'underline' | 'none';
}

h1/h2/h3/h4/h5/h6 (headings)

  • fontSize is the size of the heading's font. Defaults to 32 for H1, 24 for H2, 20 for H3, 16 for H4, 14 for H5, 12 for H6.
  • bold defines whether the heading should be bolded, defaults to false.

blockquote

  • borderColor defines the color of the rectangular border drawn to the left of blockquote text. Takes color value, defaults to darkgray.
  • borderWidth sets the width of the said border, defaults to 4.
  • gapWidth sets the width of the gap between the border and the blockquote text, defaults to 16.
  • color defines the color of blockquote's text. Takes color value, if not set makes the blockquote text the same color as the input's color prop.

codeblock

  • color defines the color of codeblock text, takes color value and defaults to black.
  • borderRadius sets the radius of codeblock's border, defaults to 8.
  • backgroundColor is the codeblock's background color, takes color value and defaults to darkgray.

code (inline code)

  • color defines the color of inline code's text, takes color value and defaults to red.
  • backgroundColor is the inline code's background color, takes color value and defaults to darkgray.

a (link)

  • color defines the color of link's text, takes color value and defaults to blue.
  • textDecorationLine decides if the links are underlined or not, takes either underline or none and defaults to underline

mention

If only a single config is given, the style applies to all mention types. You can also set a different config for each mentionIndicator that has been defined, then the prop should be a record with indicators as a keys and configs as their values.

  • color defines the color of mention's text, takes color value and defaults to blue.
  • backgroundColor is the mention's background color, takes color value and defaults to yellow.
  • textDecorationLine decides if the mentions are underlined or not, takes either underline or none and defaults to underline.

ol (ordered list)

By marker, we mean the number that denotes next lines of the list.

  • gapWidth sets the gap between the marker and the list item's text, defaults to 16.
  • marginLeft sets the margin to the left of the marker (between the marker and input's left edge), defaults to 16.
  • markerFontWeight defines the font weight of the marker, takes a fontWeight value and if not set, defaults to the same font weight as input's fontWeight prop.
  • markerColor sets the text color of the marker, takes color value and if not set, defaults to the same color as input's color prop.

ul (unordered list)

By bullet, we mean the dot that begins each line of the list.

  • bulletColor defines the color of the bullet, takes color value and defaults to black.
  • bulletSize sets both the height and the width of the bullet, defaults to 8.
  • marginLeft is the margin to the left of the bullet (between the bullet and input's left edge), defaults to 16.
  • gapWidth sets the gap between the bullet and the list item's text, defaults to 16.

ulCheckbox (checkbox list)

Allows using unordered list with checkboxes instead of bullets.

  • boxColor defines the color of the checkbox, takes color value and defaults to blue.
  • boxSize sets both the height and the width of the checkbox, defaults to 24.
  • marginLeft is the margin to the left of the checkbox (between the checkbox and input's left edge), defaults to 16.
  • gapWidth sets the gap between the checkbox and the list item's text, defaults to 16.