# @foundationui/smart-input

> Smart input/textarea component for React. Learns to provide inline, tab-completeable suggestions.

Latest version **1.0.101** (published 2023-02-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install @foundationui/smart-input
pnpm add @foundationui/smart-input
yarn add @foundationui/smart-input
bun add @foundationui/smart-input
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.101 |
| Published | 2023-02-23 |
| First published | 2022-12-30 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 3 |
| Unpacked size | 576 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | elliottburris, rothfels |

## Links

- npm: https://www.npmjs.com/package/@foundationui/smart-input
- Repository: https://github.com/foundation-ui/smart-input
- Issues: https://github.com/foundation-ui/smart-input/issues
- npm.io page: https://npm.io/package/@foundationui/smart-input

## Dependencies (3)

- [slate](https://npm.io/package/slate.md) ^0.87.0
- [slate-react](https://npm.io/package/slate-react.md) ^0.88.0
- [@foundationui/react-hooks](https://npm.io/package/@foundationui/react-hooks.md) ^0.0.9

## Recent versions

- 1.0.101 (latest) — 2023-02-23
- 1.0.100 — 2023-02-16
- 1.0.99 — 2023-02-11
- 1.0.98 — 2023-02-08
- 1.0.97 — 2023-02-08
- 1.0.96 — 2023-02-02
- 1.0.95 — 2023-02-02
- 1.0.94 — 2023-02-02
- 1.0.93 — 2023-02-02
- 1.0.92 — 2023-02-02
- 1.0.91 — 2023-02-02
- 1.0.90 — 2023-02-01
- 1.0.89 — 2023-01-29
- 1.0.88 — 2023-01-29
- 1.0.87 — 2023-01-26
- … 85 more at https://npm.io/package/@foundationui/smart-input/versions

## README

# `<SmartInput>`

Drop-in `<input>` and `<textarea>` replacement that that provides inline, tab-completable suggestions like [GitHub Copilot](https://github.com/features/copilot) and [Gmail Smart Compose](https://support.google.com/mail/answer/9116836) for any app.

![demo user composing an email with SmartInput](https://raw.githubusercontent.com/foundation-ui/assets/main/img/demo-email.gif)

The component learns from user input and makes better suggestions over time.

```jsx
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](https://jsbin.com/difibux/edit?html,js,output)
- [inline styles](https://jsbin.com/qebozab/edit?html,js,output)
- [styled-components](https://jsbin.com/faperes/edit?html,js,output)

<br>

## Install

### npm

```bash
npm install --save @foundationui/smart-input
```

### yarn

```bash
yarn add @foundationui/smart-input
```

<br>

## How it works

`<SmartInput>` completes the text you write just like [GitHub Copilot](https://github.com/features/copilot). It's not very smart at first, but it quickly learns to be useful. Start by creating a model on [foundation-ui.com](https://app.foundation-ui.com) then set the `model` property:

```jsx
<SmartInput model="foundation/hn-comment" />
```

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](https://app.foundation-ui.com).

<br>

### 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:

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

<br>

### Providing context

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

```jsx
<SmartInput
  context={JSON.stringify({
    subject: 'This is too easy to integrate',
    recipient: 'jane@doe.com',
  })}
/>
```

Don't need to worry about how you format the string, but it's useful to be descriptive. You an use an English sentence, a `JSON.stringify`'d object of key/value pairs, both, etc.

<br>

### 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](https://app.foundation-ui.com) to bootstrap the model.

You can also send your data to our data ingestion endpoint, which accepts inputs your users have already written.

```bash
curl -X POST https://api.foundation-ui.com/v0/database \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: <your api key>' \
  -d @- <<BODY
{
  "repository": "my-org/support-widget",
  "table": "Table1",
  "data": [{
    "user": "elonmusk",
    "context": "Subject: 'This is too easy to integrate'\nTo: 'support@foundation-ui.com'",
    "input": "Hey, SmartInput is awesome! It only took me a couple of minutes to",
    "output": " add it to my application."
  }]
}
BODY
```

In the example above, the `id`, `user`, `context`, and `completion`, fields are all ⚠️ optional.

<br>

### Deploy to prod

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

```jsx
<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:

0. (optional) Bootstrap your model with data on [foundation-ui.com](https://app.foundation-ui.com)
1. Replace one of the inputs in your app with `<SmartInput safeMode />`
2. Tune settings and review model performance on [foundation-ui.com](https://app.foundation-ui.com) until you are satisfied with the results

<br>

<blockquote>
🔮 <b>Coming soon</b> ✨<br>

Soon on foundation-ui.com, you'll be able to ...

- deploy a model to a small fraction of your users
- check how often they accepted completions
- A/B test different model versions
- build confidence over time

</blockquote>

<br>

### Improve your model

Once your models are live, you can play with them to make them smarter. First, take a look at your models' accepted completion rate to see how useful it is to your users.

Next, improve your model by creating different versions of your model (branches), train them with different sets of data, request completions with different parameters, A/B test branches, etc.

## :scroll: Props

<blockquote>

#### `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: string | undefined`

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

For example, it could be an English sentence description of what's happening in your app or a `JSON.stringify`'d object of useful key/value pairs.

#### `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:

```jsx
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:

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

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

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

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

```jsx
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:

```jsx
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`.

#### `onShowCompletion: ((completion: string) => void) | undefined`

Called when a non-empty completion is shown to the user.

#### `onAcceptCompletion: ((completion: string) => void) | undefined`

Called when a non-empty completion is accepted by the user.

#### `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](https://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.

</blockquote>

---
_Source: https://npm.io/package/@foundationui/smart-input · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._