InlineAutocomplete

Provides inline auto completion suggestions for an input or textarea.

Draft
Not reviewed for accessibility

On this page

import {InlineAutocomplete} from '@primer/react/drafts'

The InlineAutocomplete component extends an Input or Textarea component to provide inline suggestions, similar to those provided by a code editor.

Examples

Input components must always be accompanied by a corresponding label to improve support for assistive technologies. Examples below are provided for conciseness and may not reflect accessibility best practices.

InlineAutocomplete can be used with the FormControl component to render a corresponding label.

Multi-line input

Try typing a # symbol to see suggestions. Use Enter or click to apply a suggestion.

const options = ['javascript', 'typescript', 'css', 'html', 'webassembly']

const SimpleExample = () => {
  const [suggestions, setSuggestions] = React.useState([])

  return (
    <InlineAutocomplete
      triggers={[{triggerChar: '#'}]}
      suggestions={suggestions}
      onShowSuggestions={({query}) => setSuggestions(options.filter(tag => tag.includes(query)))}
      onHideSuggestions={() => setSuggestions([])}
    >
      <Textarea />
    </InlineAutocomplete>
  )
}

render(SimpleExample)

const options = ['javascript', 'typescript', 'css', 'html', 'webassembly']

const SimpleExample = () => {
  const [suggestions, setSuggestions] = React.useState([])

  return (
    <InlineAutocomplete
      triggers={[{triggerChar: '#'}]}
      suggestions={suggestions}
      onShowSuggestions={({query}) => setSuggestions(options.filter(tag => tag.includes(query)))}
      onHideSuggestions={() => setSuggestions([])}
    >
      <Textarea />
    </InlineAutocomplete>
  )
}

render(SimpleExample)

Single-line input

const options = ['javascript', 'typescript', 'css', 'html', 'webassembly']

const SimpleExample = () => {
  const [suggestions, setSuggestions] = React.useState([])

  return (
    <InlineAutocomplete
      triggers={[{triggerChar: '#'}]}
      suggestions={suggestions}
      onShowSuggestions={({query}) => setSuggestions(options.filter(tag => tag.includes(query)))}
      onHideSuggestions={() => setSuggestions([])}
    >
      <TextInput />
    </InlineAutocomplete>
  )
}

render(SimpleExample)

const options = ['javascript', 'typescript', 'css', 'html', 'webassembly']

const SimpleExample = () => {
  const [suggestions, setSuggestions] = React.useState([])

  return (
    <InlineAutocomplete
      triggers={[{triggerChar: '#'}]}
      suggestions={suggestions}
      onShowSuggestions={({query}) => setSuggestions(options.filter(tag => tag.includes(query)))}
      onHideSuggestions={() => setSuggestions([])}
    >
      <TextInput />
    </InlineAutocomplete>
  )
}

render(SimpleExample)

Labelled

const options = ['javascript', 'typescript', 'css', 'html', 'webassembly']

const SimpleExample = () => {
  const [suggestions, setSuggestions] = React.useState([])

  return (
    <FormControl>
      <FormControl.Label>Example</FormControl.Label>
      <InlineAutocomplete
        triggers={[{triggerChar: '#'}]}
        suggestions={suggestions}
        onShowSuggestions={({query}) => setSuggestions(options.filter(tag => tag.includes(query)))}
        onHideSuggestions={() => setSuggestions([])}
      >
        <Textarea />
      </InlineAutocomplete>
    </FormControl>
  )
}

render(SimpleExample)

const options = ['javascript', 'typescript', 'css', 'html', 'webassembly']

const SimpleExample = () => {
  const [suggestions, setSuggestions] = React.useState([])

  return (
    <FormControl>
      <FormControl.Label>Example</FormControl.Label>
      <InlineAutocomplete
        triggers={[{triggerChar: '#'}]}
        suggestions={suggestions}
        onShowSuggestions={({query}) => setSuggestions(options.filter(tag => tag.includes(query)))}
        onHideSuggestions={() => setSuggestions([])}
      >
        <Textarea />
      </InlineAutocomplete>
    </FormControl>
  )
}

render(SimpleExample)

Props

InlineAutocomplete

Name	Type	Default	Description
children Required	React.ReactNode		An `input` or `textarea` compatible component to extend. A compatible component is any component that forwards a ref and props to an underlying `input` or `textarea` element, including but not limited to `Input`, `TextArea`, `input`, `textarea`, `styled.input`, and `styled.textarea`. If the child is not compatible, a runtime `TypeError` will be thrown.
triggers Required	Array<Trigger>		Register the triggers that can cause suggestions to appear.
onShowSuggestions Required	(event: ShowSuggestionsEvent) => void		Called when a valid suggestion query is updated. This should be handled by setting the `suggestions` prop accordingly.
onShowSuggestions Required	() => void		Called when suggestions should be hidden. Set `suggestions` to `null` or an empty array in this case.
suggestions Required	Suggestion[] \| null \| 'loading'		The currently visible list of suggestions. If `loading`, a loading indicator will be shown. If `null` or empty, the list will be hidden. Suggestion sort will be preserved. Typically, this should not contain more than five or so suggestions.
tabInsertsSuggestions	boolean	false	If `true`, suggestions will be applied with both `Tab` and `Enter`, instead of just `Enter`. This may be expected behavior for users used to IDEs, but use caution when hijacking browser tabbing capability.
sx	SystemStyleObject		Style overrides to apply to the component. See also overriding styles.

Status

Alpha

Component props and basic example usage of the component are documented on primer.style/react.
Component does not have any unnecessary third-party dependencies.
Component can adapt to different themes.
Component can adapt to different screen sizes.
Component has robust unit test coverage (100% where achievable).
Component has visual regression coverage of its default and interactive states.
Component does not introduce any axe violations.
Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.

Beta

Component is used in a production application.
Common usage examples are documented on primer.style/react.
Common usage examples are documented in storybook stories.
Component has been reviewed by a systems designer and any resulting issues have been addressed.
Component does not introduce any performance regressions.

Stable

Component API has been stable with no breaking changes for at least one month.
Feedback on API usability has been sought from developers using the component and any resulting issues have been addressed.
Component has corresponding design guidelines documented in the interface guidelines.
Component has corresponding Figma component in the Primer Web library.
Tooling (such as linters, codemods, etc.) exists to prevent further use of alternatives.

Edit this page on GitHub

3 contributors

Last edited by colebemis on January 23, 2023