@foundationui/smart-input

<SmartInput>

Drop-in <input> and <textarea> replacement that that provides inline, tab-completable suggestions like GitHub Copilot and Gmail Smart Compose for any app.

The component automatically learns from user input and makes better suggestions over time. We don't call it smart for nothing!

import { SmartInput } from '@foundationui/smart-input'

function MySmartInput() {
  const [value, setValue] = useState('')
  return (
    <SmartInput
      placeholder="Type something..."
      renderText={props => <span {...props} />}
      renderCompletion={props => <span style={{ opacity: 0.4 }} {...props} />}
      value={value}
      onChange={setValue}
      multiline={false}
    />
  )
}

Examples:

• Tailwind
• inline styles
• styled-components

Install

npm

npm install --save @foundationui/smart-input

yarn

yarn add @foundationui/smart-input

How it works

<SmartInput> learns to complete the text you intend to write just like GitHub Copilot. It's not very smart at first, but it quickly learns to be useful. Start by creating a model on foundation-ui.com then set the model property:

<SmartInput model="my-org/my-input" />

As you enter keystrokes into <SmartInput>, at first it won't do anything at all but learn. Once it's confident enough, it'll start suggesting completions. You can control how confident you want <SmartInput> to be, which users should get completions, and other settings from your admin console on foundation-ui.com.

Learning user style & preferences

Not all users write the same way, and not all users want completions! Not yet. <SmartInput> learns how to be most helpful to each user if you set the user property:

<SmartInput user="a unique, stable identifier from your app" />

Providing context

To generate the best completions, give <SmartInput> whatever extra context you think would be useful. Provide data as a JSON object:

<SmartInput
  context={{
    emailSubject: 'This is too easy to integrate into my app',
    to: '[e-mail]',
  }}
/>

Bootstrap data

<SmartInput> can start learning without any data. If you want to accelerate the process, you can upload a list of strings to foundation-ui.com to bootstrap the model.

Deploy to prod

<SmartInput> is designed for your peace of mind. In addition to the controls provided for your model on foundation-ui.com, you can set the component's safeMode property to prevent showing completions:

<SmartInput safeMode />

While in safe mode, <SmartInput> will still learn from user keystrokes, but will not show any completions to users.

Therefore we recommend as the safest path to production:

1. (optional) Bootstrap your model with data on foundation-ui.com
2. Replace one of the inputs in your app with <SmartInput safeMode />
3. Tune settings and review model performance on foundation-ui.com until you are satisfied with the results
4. Turn off safeMode

API

Props

model: string | undefined

The identifier of your model, in the form {model-owner}/{model-slug}. Can be shared across different inputs, or unique per input. If you don't specify one, it will show an example completion without querying a model.

user: string | undefined

An stable identifier of the user using the input. Providing this helps the model learn a particular user's style, including if they prefer not to use completions at all.

context: Object | undefined

An object that will help the model generate better completions. Pass anything that you think is relevant to making the completions better or more personalized.

value: string

The controlled value of the input.

onChange: (newValue: string) => void

Invoked whenever the text value of the content changes. Use this to update the controlled value.

renderText: (props: any) => React.ReactElement

Invoked to display normal text, returns a React element. You should use an inline display element (e.g. span) and spread props, like so:

renderText={props => <span {...props} />}

You may add whatever styling you like like via style, className, etc.

renderCompletion: (props: any) => React.ReactElement

Invoked to display completion text, returns a React element. You should use an inline display element (e.g. span) and spread props, like so:

renderCompletion={props => <span {...props} />}

You may add whatever styling you like like via style, className, etc.

renderPlaceholder: undefined | (props: any) => React.ReactElement

Invoked to display placeholder text, returns a React element. You should use an inline display element (e.g. span) and spread props, like so:

renderCompletion={props => <span {...props} />}

You may add whatever styling you like like via style, className, etc.

WARNING: if you want to set style, make sure to merge the style from props like so:

renderCompletion={props => <span {...props} style={{...props.style, color: 'red' }} />}

placeholder: string | undefined

The text to display when value is empty. If not provided, no placeholder is displayed.

multiline: boolean | undefined

Whether or not to allow multiline text. Default false.

onBlur: React.FocusEventHandler<HTMLElement> | undefined

Standard onBlur handler, analogous to the one from <input> and <textarea> elements.

onFocus: React.FocusEventHandler<HTMLElement> | undefined

Standard onFocus handler, analogous to the one from <input> and <textarea> elements.

onKeyDown: React.KeyboardEventHandler<HTMLElement> | undefined

Standard onKeyDown handler, analogous to the one from <input> and <textarea> elements. Note that this handler is called after any keyboard events captured by <SmartInput> (e.g. Tab to accept a suggestion).

disabled: boolean | undefined

Whether the input is editable. If true, the input is read-only.

safeMode: boolean | undefined

Whether to run in safe mode. In safe mode, no completions will be shown, but your input will still collect data to learn to generate completions. You can see the completions that would have been shown to your users on foundation-ui.com

container: React.ElementType<P> | undefined

Element to use as the wrapper component. If not provided, the component will render as a <div> with contenteditable="true".

containerProps: P | undefined

Props that will get passed to the container element, when one is provided.