Add anchorMode prop with left and caret options

README.md

@@ -107,6 +107,7 @@ The `MentionsInput` component supports the following props:
 | onKeyDown                  | function (event)                                                       | empty function | A callback that is invoked when the user presses a key in the mentions input                                                          |
 | singleLine                 | boolean                                                                | `false`        | Renders a single line text input instead of a textarea, if set to `true`                                                              |
 | autoResize                 | boolean                                                                | `false`        | When `true`, resizes the textarea to match its scroll height after each input change (ignored when `singleLine` is `true`)           |
+| anchorMode                 | `'caret' \| 'left'`                                                    | `'caret'`      | Controls whether the overlay follows the caret (`'caret'`) or pins to the control’s leading edge (`'left'`)                         |
 | onMentionBlur              | function (event, clickedSuggestion)                                    | `undefined`    | Receives an extra `clickedSuggestion` flag when focus left via the suggestions list                                                   |
 | suggestionsPortalHost      | DOM Element                                                            | undefined      | Render suggestions into the DOM in the supplied host element.                                                                         |
 | inputRef                   | React ref                                                              | undefined      | Accepts a React ref to forward to the underlying input element                                                                        |

demo/src/examples/Examples.tsx

@@ -13,6 +13,7 @@ import AllowSpaceInQuery from './AllowSpaceInQuery'
 import AlphabetRegexTrigger from './AlphabetRegexTrigger'
 import MentionSelection from './MentionSelection'
 import AutoResize from './AutoResize'
+import LeftAnchored from './LeftAnchored'
 
 const users = [
   {
@@ -91,6 +92,7 @@ export default function Examples() {
       <Emojis data={users} onAdd={(addParams) => console.log('onAdd', addParams)} />
       <SuggestionPortal data={users} />
       <CustomSuggestionsContainer data={users} />
+      <LeftAnchored data={users} />
     </div>
   )
 }

demo/src/examples/LeftAnchored.tsx

@@ -0,0 +1,31 @@
+import React, { useState } from 'react'
+
+import { Mention, MentionsInput } from '../../../src'
+import type { MentionDataItem, MentionsInputChangeEvent } from '../../../src'
+import ExampleCard from './ExampleCard'
+
+export default function LeftAnchored({ data }: { data: MentionDataItem[] }) {
+  const [value, setValue] = useState('')
+
+  const onMentionsChange = ({ value: nextValue }: MentionsInputChangeEvent) => {
+    setValue(nextValue)
+  }
+
+  return (
+    <ExampleCard
+      title="Left anchored suggestions"
+      description="Pop the overlay from the input edge instead of the caret, ideal for wide inputs."
+    >
+      <MentionsInput
+        anchorMode="left"
+        value={value}
+        onMentionsChange={onMentionsChange}
+        className="mentions"
+        placeholder="Start typing '@' to mention"
+        a11ySuggestionsListLabel="Suggested mentions"
+      >
+        <Mention data={data} />
+      </MentionsInput>
+    </ExampleCard>
+  )
+}

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "react-mentions-ts",
 	"private": false,
-	"version": "5.4.3",
+	"version": "5.4.4",
 	"description": "A React component that enables Facebook/Twitter-style @mentions and tagging in textarea inputs with full TypeScript support.",
 	"type": "module",
 	"main": "./dist/index.cjs",
@@ -97,19 +97,19 @@
 		"@testing-library/react": "^16.3.0",
 		"@testing-library/user-event": "^14.6.1",
 		"@types/jest": "^30.0.0",
-		"@types/node": "^24.9.2",
+		"@types/node": "^24.10.0",
 		"@types/react": "^19.2.2",
 		"@types/react-dom": "^19.2.2",
 		"@vitejs/plugin-react": "^5.1.0",
 		"class-variance-authority": "^0.7.1",
 		"clsx": "^2.1.1",
-		"eslint": "^9.38.0",
+		"eslint": "^9.39.1",
 		"eslint-config-prettier": "^10.1.8",
 		"eslint-plugin-code-complete": "^1.1.2",
 		"eslint-plugin-import": "^2.32.0",
 		"eslint-plugin-jest": "^29.0.1",
 		"eslint-plugin-jsx-a11y": "^6.10.2",
-		"eslint-plugin-package-json": "^0.59.0",
+		"eslint-plugin-package-json": "^0.64.0",
 		"eslint-plugin-prettier": "^5.5.4",
 		"eslint-plugin-promise": "^7.2.1",
 		"eslint-plugin-react": "^7.37.5",
@@ -125,19 +125,19 @@
 		"jest-environment-jsdom": "^30.2.0",
 		"jiti": "^2.6.1",
 		"jsonc-eslint-parser": "^2.4.1",
-		"knip": "^5.66.4",
+		"knip": "^5.67.1",
 		"prettier": "^3.6.2",
 		"publint": "^0.3.15",
 		"react": "^19.2.0",
 		"react-dom": "^19.2.0",
-		"rimraf": "^6.0.1",
+		"rimraf": "^6.1.0",
 		"tailwind-merge": "^3.3.1",
 		"ts-jest": "^29.4.5",
 		"ts-node": "^10.9.2",
 		"tsup": "^8.5.0",
 		"typescript": "^5.9.3",
-		"typescript-eslint": "^8.46.2",
-		"vite": "^7.1.12"
+		"typescript-eslint": "^8.46.3",
+		"vite": "^7.2.1"
 	},
 	"peerDependencies": {
 		"class-variance-authority": ">=0.6.0",

src/MentionsInput.spec.tsx

@@ -371,7 +371,7 @@
   })
 
   it('should load suggestions from async data providers.', async () => {
     const asyncData = jest.fn(async (query: string) => {
       await Promise.resolve()
       return [
         { id: 'async-one', display: 'Async One' },
@@ -661,7 +661,7 @@
         </MentionsInput>
       )
 
       const computed = window.getComputedStyle(combobox)
       const borderTop = Number.parseFloat(computed.borderTopWidth || '0')
       const borderBottom = Number.parseFloat(computed.borderBottomWidth || '0')
       expect(Number.parseFloat(combobox.style.height)).toBe(scrollHeight + borderTop + borderBottom)
@@ -693,7 +693,7 @@
         </MentionsInput>
       )
 
       const computed = window.getComputedStyle(combobox)
       const borderTop = Number.parseFloat(computed.borderTopWidth || '0')
       const borderBottom = Number.parseFloat(computed.borderBottomWidth || '0')
       expect(Number.parseFloat(combobox.style.height)).toBe(scrollHeight + borderTop + borderBottom)
@@ -740,7 +740,7 @@
       })
 
       await waitFor(() => {
         const computed = window.getComputedStyle(combobox)
         const borderTop = Number.parseFloat(computed.borderTopWidth || '0')
         const borderBottom = Number.parseFloat(computed.borderBottomWidth || '0')
         expect(Number.parseFloat(combobox.style.height)).toBe(
@@ -765,7 +765,7 @@
 
     it('adds border widths to the measured height', () => {
       const onMentionsChange = jest.fn()
       const getComputedStyleSpy = jest.spyOn(window, 'getComputedStyle').mockReturnValue({
         borderTopWidth: '4px',
         borderBottomWidth: '6px',
       } as unknown as CSSStyleDeclaration)
@@ -824,7 +824,7 @@
         </MentionsInput>
       )
 
       const computed = window.getComputedStyle(textarea)
       const borderTop = Number.parseFloat(computed.borderTopWidth || '0')
       const borderBottom = Number.parseFloat(computed.borderBottomWidth || '0')
       expect(Number.parseFloat(textarea.style.height)).toBe(scrollHeight + borderTop + borderBottom)
@@ -1396,7 +1396,7 @@
       const textarea = screen.getByRole('combobox')
       fireEvent.focus(textarea)
 
       const initialIndex = textarea.value.indexOf('First') + 1
       expect(initialIndex).toBeGreaterThan(0)
       textarea.setSelectionRange(initialIndex, initialIndex)
       fireEvent.select(textarea)
@@ -1412,7 +1412,7 @@
         </MentionsInput>
       )
 
       const updatedIndex = textarea.value.indexOf('Second') + 1
       expect(updatedIndex).toBeGreaterThan(0)
       textarea.setSelectionRange(updatedIndex, updatedIndex)
       fireEvent.select(textarea)
@@ -1851,7 +1851,7 @@
       const suggestions = document.createElement('div')
       const container = document.createElement('div')
       highlighter.style.fontSize = '18px'
-      suggestions.style.marginLeft = '5px'
+      suggestions.style.marginLeft = '0px'
       suggestions.style.marginTop = '7px'
       Object.defineProperty(highlighter, 'getBoundingClientRect', {
         value: () => ({
@@ -1871,6 +1871,10 @@
       instance.highlighterElement = highlighter
       instance.suggestionsElement = suggestions
       instance.containerElement = container
+      highlighter.scrollLeft = 5
+      highlighter.scrollTop = 3
+      Object.defineProperty(highlighter, 'offsetWidth', { value: 200, configurable: true })
+      Object.defineProperty(container, 'offsetWidth', { value: 320, configurable: true })
 
       const setStateMock = jest.spyOn(instance, 'setState').mockImplementation((update, cb) => {
         const nextState =
@@ -1887,9 +1891,92 @@
       })
 
       expect(instance.state.suggestionsPosition.position).toBe('fixed')
-      expect(typeof instance.state.suggestionsPosition.left).toBe('number')
+      expect(instance.state.suggestionsPosition.left).toBe(9)
       expect(typeof instance.state.suggestionsPosition.top).toBe('number')
 
+      act(() => {
+        instance.state.suggestionsPosition = {}
+      })
+      Object.assign(instance.props, { anchorMode: 'left' })
+
+      act(() => {
+        instance.updateSuggestionsPosition()
+      })
+
+      expect(instance.state.suggestionsPosition.position).toBe('fixed')
+      expect(instance.state.suggestionsPosition.left).toBe(4)
+
+      highlighter.remove()
+      suggestions.remove()
+      container.remove()
+      setStateMock.mockRestore()
+      unmount()
+    })
+
+    it('anchors suggestions to the control edge when using anchorMode="left" outside portals.', async () => {
+      const ref = React.createRef<MentionsInput>()
+      const { unmount } = render(
+        <MentionsInput ref={ref} value="" anchorMode="left">
+          <Mention trigger="@" data={data} />
+        </MentionsInput>
+      )
+
+      await waitFor(() => {
+        expect(ref.current).not.toBeNull()
+      })
+
+      const instance = ref.current as unknown as any
+      Object.defineProperty(instance, 'resolvePortalHost', {
+        value: () => null,
+        configurable: true,
+        writable: true,
+      })
+
+      const highlighter = document.createElement('div')
+      const suggestions = document.createElement('div')
+      const container = document.createElement('div')
+      highlighter.style.fontSize = '16px'
+      Object.defineProperty(highlighter, 'getBoundingClientRect', {
+        value: () => ({
+          left: 2,
+          top: 8,
+          right: 0,
+          bottom: 0,
+          width: 0,
+          height: 0,
+        }),
+      })
+      Object.defineProperty(highlighter, 'offsetWidth', { value: 180, configurable: true })
+      Object.defineProperty(container, 'offsetWidth', { value: 220, configurable: true })
+      Object.defineProperty(suggestions, 'offsetHeight', { value: 40, configurable: true })
+      document.body.append(highlighter)
+      document.body.append(suggestions)
+      document.body.append(container)
+
+      highlighter.scrollLeft = 14
+      highlighter.scrollTop = 5
+
+      instance.highlighterElement = highlighter
+      instance.suggestionsElement = suggestions
+      instance.containerElement = container
+      instance.state.caretPosition = { left: 32, top: 18 }
+      instance.state.suggestionsPosition = {}
+
+      const setStateMock = jest.spyOn(instance, 'setState').mockImplementation((update, cb) => {
+        const nextState =
+          typeof update === 'function' ? update(instance.state, instance.props) : update
+        Object.assign(instance.state, nextState)
+        cb?.()
+      })
+
+      act(() => {
+        instance.updateSuggestionsPosition()
+      })
+
+      expect(instance.state.suggestionsPosition.position).toBeUndefined()
+      expect(instance.state.suggestionsPosition.left).toBe(0)
+      expect(instance.state.suggestionsPosition.right).toBeUndefined()
+
       highlighter.remove()
       suggestions.remove()
       container.remove()
@@ -1941,6 +2028,21 @@
       }
       ;(globalThis as any).ResizeObserver = MockResizeObserver
 
+      const originalAdd = window.addEventListener
+      const originalRemove = window.removeEventListener
+      const handlers: Partial<Record<string, EventListener>> = {}
+      const addListener = jest
+        .spyOn(window, 'addEventListener')
+        .mockImplementation((type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions) => {
+          handlers[type] = listener as EventListener
+          return originalAdd.call(window, type, listener, options)
+        })
+      const removeListener = jest
+        .spyOn(window, 'removeEventListener')
+        .mockImplementation((type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions) => {
+          return originalRemove.call(window, type, listener, options)
+        })
+
       const bridgeElement = instance.renderMeasurementBridge() as React.ReactElement
       const { unmount: unmountBridge } = render(bridgeElement)
 
@@ -1957,10 +2059,32 @@
       expect(syncScroll.mock.calls.length).toBe(syncCalls + 1)
       expect(updatePosition.mock.calls.length).toBe(positionCalls + 1)
 
+      act(() => {
+        window.dispatchEvent(new Event('resize'))
+      })
+
+      expect(syncScroll.mock.calls.length).toBeGreaterThan(syncCalls + 1)
+      expect(updatePosition.mock.calls.length).toBeGreaterThan(positionCalls + 1)
+
+      act(() => {
+        window.dispatchEvent(new Event('orientationchange'))
+      })
+
+      expect(syncScroll.mock.calls.length).toBeGreaterThan(syncCalls + 2)
+      expect(updatePosition.mock.calls.length).toBeGreaterThan(positionCalls + 2)
+
       unmountBridge()
       for (const observer of observers) {
         expect(observer.disconnect).toHaveBeenCalled()
       }
+      expect(handlers.resize).toBeDefined()
+      expect(handlers.orientationchange).toBeDefined()
+      expect(addListener).toHaveBeenCalledWith('resize', handlers.resize)
+      expect(addListener).toHaveBeenCalledWith('orientationchange', handlers.orientationchange)
+      expect(removeListener).toHaveBeenCalledWith('resize', handlers.resize)
+      expect(removeListener).toHaveBeenCalledWith('orientationchange', handlers.orientationchange)
+      addListener.mockRestore()
+      removeListener.mockRestore()
       ;(globalThis as any).ResizeObserver = originalResizeObserver
       unmount()
     })

src/MentionsInput.tsx

@@ -46,6 +46,7 @@
   MentionSelectionState,
   MentionChildConfig,
   MentionsInputProps,
+  MentionsInputAnchorMode,
   MentionsInputState,
   MentionsInputClassNames,
   MentionsInputChangeTrigger,
@@ -66,7 +67,7 @@
     // eslint-disable-next-line @typescript-eslint/require-await
     return async (query: string) =>
       items.flatMap((item) => {
         const index = getSubstringIndex(item.display || String(item.id), query, ignoreAccents)
         return index >= 0
           ? [
               {
@@ -192,6 +193,7 @@
 
 const HANDLED_PROPS: Array<keyof MentionsInputProps<any>> = [
   'singleLine',
+  'anchorMode',
   'suggestionsPlacement',
   'a11ySuggestionsListLabel',
   'value',
@@ -223,6 +225,7 @@
   } = {
     singleLine: false,
     autoResize: false,
+    anchorMode: 'caret',
     suggestionsPlacement: 'below',
     onKeyDown: () => null,
     onSelect: () => null,
@@ -560,15 +563,15 @@
       value: getPlainText(this.props.value ?? '', this.state.config),
       onScroll: this.updateHighlighterScroll,
       'data-slot': 'input',
       'data-single-line': singleLine ? 'true' : undefined,
       'data-multi-line': singleLine ? undefined : 'true',
     }
 
     const inlineStyle: CSSProperties = {
       background: 'transparent',
     }
 
     if (!singleLine && isMobileSafari) {
       inlineStyle.marginTop = 1
       inlineStyle.marginLeft = -3
     }
@@ -577,7 +580,7 @@
       props.style = inlineStyle
     }
 
     if (!readOnly && !disabled) {
       Object.assign(props, {
         onChange: this.handleChange,
         onSelect: this.handleSelect,
@@ -606,7 +609,7 @@
       const existingDescribedBy =
         typeof props['aria-describedby'] === 'string' ? props['aria-describedby'] : undefined
       const describedBy = [existingDescribedBy, this.inlineAutocompleteLiveRegionId]
         .filter((value): value is string => Boolean(value && value.trim().length > 0))
         .join(' ')
       props['aria-describedby'] = describedBy || undefined
     }
@@ -627,7 +630,7 @@
             ...inputProps,
           } as any
         )
       : singleLine
         ? this.renderInput(inputProps)
         : this.renderTextarea(inputProps)
 
@@ -693,7 +696,7 @@
       if (globalThis.window !== undefined && typeof globalThis.getComputedStyle === 'function') {
         const computed = globalThis.getComputedStyle(element)
         const parse = (value: string | null | undefined) =>
           value ? Number.parseFloat(value) || 0 : 0
         borderAdjustment = parse(computed.borderTopWidth) + parse(computed.borderBottomWidth)
       }
 
@@ -1339,7 +1342,7 @@
     if ('isComposing' in native && typeof native.isComposing === 'boolean') {
       this._isComposing = native.isComposing
     }
     const value = this.props.value || ''
 
     let newPlainTextValue = ev.target.value
 
@@ -1603,6 +1606,8 @@
   updateSuggestionsPosition = (): void => {
     const { caretPosition } = this.state
     const { suggestionsPlacement = 'below' } = this.props
+    const anchorMode: MentionsInputAnchorMode = this.props.anchorMode ?? 'caret'
+    const anchorToLeft = anchorMode === 'left'
     const resolvedPortalHost = this.resolvePortalHost()
 
     const suggestions = this.suggestionsElement
@@ -1617,7 +1622,7 @@
     const caretOffsetParentRect = highlighter.getBoundingClientRect()
     const caretHeight = getComputedStyleLengthProp(highlighter, 'font-size')
     const viewportRelative = {
-      left: caretOffsetParentRect.left + caretPosition.left,
+      left: caretOffsetParentRect.left + (anchorToLeft ? 0 : caretPosition.left),
       top: caretOffsetParentRect.top + caretPosition.top + caretHeight,
     }
     const viewportHeight = Math.max(document.documentElement.clientHeight, window.innerHeight || 0)
@@ -1636,7 +1641,9 @@
       left -= getComputedStyleLengthProp(suggestions, 'margin-left')
       top -= getComputedStyleLengthProp(suggestions, 'margin-top')
       // take into account highlighter/textinput scrolling:
-      left -= highlighter.scrollLeft
+      if (!anchorToLeft) {
+        left -= highlighter.scrollLeft
+      }
       top -= highlighter.scrollTop
       // guard for mentions suggestions list clipped by window edges
       const maxLeft = Math.max(0, viewportWidth - width)
@@ -1655,10 +1662,12 @@
       const containerWidth = container.offsetWidth
       const width = Math.min(desiredWidth, containerWidth)
       position.width = width
-      const left = caretPosition.left - highlighter.scrollLeft
+      const left = anchorToLeft ? 0 : caretPosition.left - highlighter.scrollLeft
       const top = caretPosition.top - highlighter.scrollTop
       // guard for mentions suggestions list clipped by right edge of window
-      if (left + width > containerWidth) {
+      if (anchorToLeft) {
+        position.left = 0
+      } else if (left + width > containerWidth) {
         position.right = 0
       } else {
         position.left = left
@@ -1679,7 +1688,8 @@
       position.left === this.state.suggestionsPosition.left &&
       position.top === this.state.suggestionsPosition.top &&
       position.position === this.state.suggestionsPosition.position &&
-      position.width === this.state.suggestionsPosition.width
+      position.width === this.state.suggestionsPosition.width &&
+      position.right === this.state.suggestionsPosition.right
     ) {
       return
     }
@@ -2076,6 +2086,24 @@
     [observe, suggestions, updateSuggestions]
   )
 
+  useLayoutEffect(() => {
+    if (typeof window === 'undefined') {
+      return undefined
+    }
+
+    const handleViewportChange = () => {
+      updateAll()
+    }
+
+    window.addEventListener('resize', handleViewportChange)
+    window.addEventListener('orientationchange', handleViewportChange)
+
+    return () => {
+      window.removeEventListener('resize', handleViewportChange)
+      window.removeEventListener('orientationchange', handleViewportChange)
+    }
+  }, [updateAll])
+
   useLayoutEffect(() => {
     if (!input) {
       return undefined

src/SuggestionsOverlay.tsx

@@ -46,7 +46,7 @@ interface SuggestionsOverlayProps<Extra extends Record<string, unknown> = Record
 }
 
 const overlayStyles = cva(
-  'z-[100] mt-3 w-full min-w-[16rem] overflow-hidden rounded-2xl border border-border bg-popover shadow-xl ring-1 ring-ring backdrop-blur supports-[backdrop-filter]:bg-popover/95'
+  'z-[100] mt-3 w-full min-w-[16rem] overflow-hidden rounded-xl border border-border bg-popover shadow-xl ring-1 ring-ring backdrop-blur supports-[backdrop-filter]:bg-popover/95'
 )
 const listStyles =
   'm-0 max-h-64 list-none divide-y divide-border overflow-y-auto scroll-py-1 p-0 focus:outline-none'