use-chat-submit

The hook provides two modes to handle how the Enter key behaves, which is useful for balancing ease of use with IME (Input Method Editor) stability (e.g., for Japanese or Chinese users).

• mod-enter: Recommended for IME-heavy languages. Enter and Shift+Enter both insert a line break. Cmd/Ctrl+Enter triggers the submission.
• enter: Standard chat behavior. Enter triggers submission. Shift+Enter inserts a line break. Cmd/Ctrl+Enter also triggers submission.

Both modes include a two-step check using KeyboardEvent.isComposing to ensure the hook never submits while a user is composing characters via an IME.

| `options.mode` | Enter   | Shift+Enter | Cmd/Ctrl+Enter |
| -------------- | ------- | ----------- | -------------- |
| `mod-enter`    | Line break | Line break  | Submit         |
| `enter`        | Submit  | Line break  | Submit         |

Install the package using your preferred package manager:

pnpm add use-chat-submit
# or
npm i use-chat-submit
# or
yarn add use-chat-submit

The hook uses a layered event handling approach via getTextareaProps:

1. User Handlers First: If you provide an onKeyDown prop to getTextareaProps, it is executed before the library's internal logic.
2. Interruption Support: If your custom handler calls event.preventDefault() or event.stopPropagation(), the library's internal submission logic will be skipped.
3. IME Safety: The hook monitors compositionstart, compositionend, and compositioncancel events. It prevents submission while the user is composing characters (e.g., using Japanese or Chinese IMEs) to avoid submitting partial or incorrect text.

The useChatSubmit hook returns an object containing the following properties:

When using use-chat-submit, keep the following constraints in mind:

• Element Support: Only <textarea> is supported. <input> elements are not supported because they do not allow multi-line input.
• React Version: Requires React 19+ as a peer dependency.
• Submission Logic: The hook does not submit if the textarea is disabled or readOnly. If allowEmptySubmit is set to false (the default), it will not submit if the trimmed value is empty.

The getUserAgentSummary function provides information about the user's device, specifically whether it is an Apple device and whether it is a mobile device. It first attempts to use the modern navigator.userAgentData API and falls back to parsing the navigator.userAgent string if necessary.

Returns undefined if called in a non-browser environment (where window is undefined).

Return Type: UserAgentSummary object:

• isAppleDevice: boolean (true if platform is macOS or iOS)
• isMobile: boolean (true if mobile device)

const summary = getUserAgentSummary();
if (summary) {
  console.log(summary.isAppleDevice, summary.isMobile);
}

The beautifyKeyTextList function is a convenience wrapper that applies beautifyKeyText to an array of keys. This is useful for displaying keyboard shortcut combinations (e.g., ⌘ + K).

Parameters:

• keys: An array of BeautifyKeyTextInputKey ('meta' | 'ctrl' | 'shift' | 'enter').
• isApple: Boolean indicating if the user is on an Apple device.
• hintLabelStyle: The desired output style ('auto' | 'symbols' | 'text').

Returns: An array of formatted strings.

import { beautifyKeyTextList } from './utils';

const formattedKeys = beautifyKeyTextList({
  keys: ['meta', 'k'],
  isApple: true,
  hintLabelStyle: 'symbols'
});
// Note: 'k' is passed through as is because it's not a BeautifyKeyTextInputKey,
// but the function maps over the provided array.
// Result: ["⌘", "k"]

The useChatSubmit hook returns an object with the following properties:

• getTextareaProps: A function that accepts React.TextareaHTMLAttributes and returns composed props including a merged ref and onKeyDown handler.
• textareaRef: A read-only React.RefObject pointing to the HTMLTextAreaElement.
• triggerSubmit: A function to manually trigger the onSubmit callback (respecting allowEmptySubmit and element state).
• shortcutHintLabels: An object containing submit and lineBreak metadata (keys and uniqueness) used for rendering UI hints. Returns undefined if keys cannot be resolved.
• isEnabled: A boolean indicating if the submission logic is currently active.
• isComposingRef: A read-only React.RefObject<boolean> indicating if an IME composition is currently in progress.