## Overview [#overview]
The `Input` component is a flexible form control for collecting user text input. It supports various input types, decorative elements like addons and icons, multiple sizes, and URL state synchronization for preserving input values across page navigation.
## Usage [#usage]
```tsx
import {
Input,
InputAddon,
InputGroup,
InputWrapper,
} from "@tilt-legal/cubitt-components/primitives";
```
```tsx
```
Using Cubitt's URL-state hooks, you can sync the input value with the URL by providing a `paramName`:
```tsx
// Value syncs with ?search=... in URL
// Advanced options:
console.log('Filter:', value)}
/>
```
## Examples [#examples]
Looking for date or time inputs? See the Date Input docs for `DateInput`,
`DateInputRoot`, and `TimeInputRoot`.
### Basic Input [#basic-input]
A simple text input field.
```tsx
import { Input } from "@tilt-legal/cubitt-components/primitives";
;
```
### Disabled and Readonly [#disabled-and-readonly]
Input fields that are disabled or readonly.
```tsx
import { Input } from "@tilt-legal/cubitt-components/primitives";
```
### With Addons [#with-addons]
Use `InputGroup` with `InputAddon` to attach elements to an input. Each element maintains its own visual boundary.
```tsx
import {
Button,
Input,
InputAddon,
InputGroup,
} from "@tilt-legal/cubitt-components/primitives";
import { Input, InputWrapper } from "@tilt-legal/cubitt-components/primitives";
import {
CurrencyEuro } from "@tilt-legal/cubitt-icons/ui/outline";
Text
```
### With Embedded Elements [#with-embedded-elements]
Use `InputWrapper` to place elements inside an input. Elements appear embedded within a single field.
```tsx
import { Button } from "@tilt-legal/cubitt-components/primitives";
import {
CurrencyEuro,
Xmark } from "@tilt-legal/cubitt-icons/ui/outline";
@tilt.legal
```
### File Input [#file-input]
Input for file uploads.
```tsx
import { Input } from "@tilt-legal/cubitt-components/primitives";
;
```
### Copy to Clipboard [#copy-to-clipboard]
Input with a copy-to-clipboard button.
```tsx
import {
useRef } from "react";
import { useBoolean, useCopyToClipboard, useDebounceCallback } from "@tilt-legal/cubitt-components/utilities/hooks";
import { Button } from "@tilt-legal/cubitt-components/primitives";
import { Input, InputWrapper } from "@tilt-legal/cubitt-components/primitives";
import {
Tooltip,
TooltipContent,
TooltipProvider,
TooltipTrigger,
} from "@tilt-legal/cubitt-components/primitives";
import {
Check,
Copy } from "@tilt-legal/cubitt-icons/ui/outline";
export default function CopyToClipboardExample() {
const { value: copied,
setFalse,
setTrue } = useBoolean(false);
const [,
copyToClipboard] = useCopyToClipboard();
const resetCopied = useDebounceCallback(() => {
setFalse();
},
2000);
const inputRef = useRef(null);
const handleCopy = async () => {
if (!inputRef.current) {
return;
}
const success = await copyToClipboard(inputRef.current.value);
if (!success) {
return;
}
setTrue();
resetCopied();
};
return (
}
>
{copied ? (
) : (
)}
Copy to clipboard
);
}
```
### Clearable Input [#clearable-input]
Input with a clear button.
```tsx
import { useRef,
useState } from "react";
import { Button } from "@tilt-legal/cubitt-components/primitives";
import { Input, InputWrapper } from "@tilt-legal/cubitt-components/primitives";
import {
Xmark } from "@tilt-legal/cubitt-icons/ui/outline";
export default function ClearableExample() {
const [inputValue,
setInputValue] = useState("Click to clear");
const inputRef = useRef(null);
const handleClearInput = () => {
setInputValue("");
if (inputRef.current) {
inputRef.current.focus();
}
};
return (
setInputValue(e.target.value)}
/>
{inputValue !== "" && (
)}
);
}
```
### Sizes [#sizes]
Input fields in different sizes.
```tsx
import { Input } from "@tilt-legal/cubitt-components/primitives";
```
### Inline [#inline]
Use `variant="inline"` for inputs that look like text. Useful for editable titles, inline editing, or any context where you want the input to blend with surrounding text.
```tsx
import { Input } from "@tilt-legal/cubitt-components/primitives";
This is an example of an inline input that looks like editable text.
```
### URL State [#url-state]
Input with URL state synchronization.
```tsx
import { Input } from "@tilt-legal/cubitt-components/primitives";
;
```
***
## API Reference [#api-reference]
### Input [#input]
The main input component for text entry. Built on [Base UI Input](https://base-ui.com/react/components/input) with additional URL state management capabilities.
| Prop | Type | Default | Description |
| ------------- | ----------------------- | ----------- | --------------------------------------------------- |
| `type` | `string` | `"text"` | Input type (text, email, password, etc.) |
| `variant` | `"default" \| "inline"` | `"default"` | Visual style. Use `inline` for text-like inputs |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the input (ignored when `variant="inline"`) |
| `placeholder` | `string` | - | Placeholder text |
| `disabled` | `boolean` | `false` | Whether the input is disabled |
| `readOnly` | `boolean` | `false` | Whether the input is read-only |
| `className` | `string` | - | Additional CSS classes |
#### URL State Props [#url-state-props]
The following props enable URL state management by syncing the input value with URL parameters via TanStack Router search params. When `paramName` is provided, the input's value will be reflected in the URL.
| Prop | Type | Default | Description |
| --------------------- | --------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `paramName` | `string` | - | URL parameter name for syncing state with URL. When provided, enables URL state management. |
| `paramValue` | `string` | - | Controlled value for the URL parameter (syncs with input `value`). |
| `onUrlValueChange` | `(value: string \| null) => void` | - | Callback when URL parameter value changes. |
| `paramClearOnDefault` | `boolean` | `true` | Remove URL param when value equals default. |
| `paramThrottle` | `number` | - | Throttle URL updates in milliseconds. |
| `paramDebounce` | `number` | - | Debounce URL updates in milliseconds. |
### InputAddon [#inputaddon]
A decorative addon element for the input.
| Prop | Type | Default | Description |
| ----------- | ---------------------- | ------- | ---------------------- |
| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size to match input |
| `className` | `string` | - | Additional CSS classes |
### InputGroup [#inputgroup]
Container for attaching `InputAddon` elements to an input. Each element maintains its own visual boundary.
| Prop | Type | Default | Description |
| ----------- | -------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |
### InputWrapper [#inputwrapper]
Container for placing icons or buttons inside an input. Elements appear embedded within a single field. Size is automatically detected from the `Input` inside.
| Prop | Type | Default | Description |
| ----------- | -------- | ------- | ---------------------- |
| `className` | `string` | - | Additional CSS classes |