Text Input
A text input is a basic field that allows users to enter text. It’s one of the most common elements in digital interfaces, used for everything from search boxes to form fields.
import {QTextInput} from "@qui/react"
Examples
Showcase
Small (s)
Medium (m)
Large (l)
import {ReactNode} from "react"import {Search} from "lucide-react"import {QTextInput} from "@qui/react"export default function Showcase(): ReactNode {return (<div className="grid grid-cols-[160px,300px] items-center justify-center gap-4 py-1"><div className="text-primary q-font-heading-xs">Small (s)</div><QTextInputfullWidthplaceholder="Search..."size="s"startIcon={Search}/><div className="text-primary q-font-heading-xs">Medium (m)</div><QTextInputfullWidthplaceholder="Search..."size="m"startIcon={Search}/><div className="text-primary q-font-heading-xs">Large (l)</div><QTextInputfullWidthplaceholder="Search..."size="l"startIcon={Search}/></div>)}
Customization
Use the label, hint, and error props to describe the element.
Error
import {ReactNode} from "react"import {Search} from "lucide-react"import {QTextInput} from "@qui/react"export default function Customization(): ReactNode {return (<div className="grid justify-center gap-y-5"><QTextInputendIcon={Search}fullWidthhint="Hint"label="Label"placeholder="Search..."/><QTextInputendIcon={Search}fullWidthhint={<span className="text-primary q-font-metadata-sm">Custom Hint</span>}label={<span className="text-primary q-font-heading-xxs">Custom Label</span>}placeholder="Search..."/><QTextInputendIcon={Search}error="Error"fullWidthlabel="Label"placeholder="Search..."/></div>)}
States
Supply disabled or readOnly to disable interactions.
Disabled
Read Only
import {ReactNode} from "react"import {Lock, Search} from "lucide-react"import {QTextInput} from "@qui/react"export default function States(): ReactNode {return (<div className="grid justify-center"><div className="grid w-[225px] gap-2"><div className="text-primary q-font-heading-xs">Disabled</div><QTextInputdefaultValue="Foo"disabledendIcon={Search}label="Label"placeholder="Search..."/><div className="mt-4 text-primary q-font-heading-xs">Read Only</div><QTextInputdefaultValue="Bar"endIcon={Lock}label="Name"placeholder="Enter your name..."readOnly/></div></div>)}
Input Customization
Use inputProps to pass properties to the underlying <input>
element.
import {ReactNode, useState} from "react"import {Eye, EyeOff} from "lucide-react"import {QIconButton, QTextInput} from "@qui/react"export default function InputProps(): ReactNode {const [showPassword, setShowPassword] = useState(false)return (<div className="grid justify-center gap-4"><QTextInputclassName="min-w-[225px]"defaultValue={50}inputProps={{type: "number"}}label="Number Input"/><QTextInputclassName="min-w-[225px]"defaultValue="password"endIcon={<QIconButtonaria-label={showPassword ? "Hide Password" : "Show Password"}denseicon={showPassword ? EyeOff : Eye}onClick={() => setShowPassword((prevState) => !prevState)}style={{paddingLeft: 0, paddingRight: 0}}/>}inputProps={{type: showPassword ? "text" : "password"}}label="Password Input"/></div>)}
Controlled
The component can be controlled or uncontrolled.
When you supply the onChange and value props, the component is controlled
. Otherwise, the component is uncontrolled
and the value is tracked internally.
Learn more about controlled and uncontrolled components in the related React Documentation.
import {ReactNode, useState} from "react"import {QTextInput} from "@qui/react"export default function Controlled(): ReactNode {const [value, setValue] = useState("foo")return (<div className="grid justify-center"><div className="flex flex-col gap-4 sm:flex-row"><QTextInputclassName="min-w-[200px]"label="Controlled"onChange={(event, value) => {setValue(value)}}value={value}/><QTextInputclassName="min-w-[200px]"defaultValue="bar"label="Uncontrolled"/></div></div>)}
API
Props
Name & Description | Option(s) | Default |
---|---|---|
The component used for the root node. It can be a React component or
element. |
| 'div' |
If true , React will focus the component on mount. |
| |
The className property of the Element
interface gets and sets the value of the
class attribute
of the specified element. |
| |
If true, the component will render a clear icon which resets the
input field on click. |
| true |
Default input value. |
| |
If true, the component will not be interactive and will appear dimmed. |
| false |
lucide-react icon, positioned after the input. If supplied as a
LucideIcon , the size will automatically match the size prop.
Supply as a ReactElement for additional customization. https://lucide.dev |
| |
Optional error, triggers the invalid style variant if supplied. This element
is automatically associated with the component's input element for optimal
accessibility. | ReactNode | |
Specifies the id of the <form> this input belongs to. If omitted, it’s the
closest parent form. |
| |
If true, the component will extend to fill the entire width of its parent
container. |
| |
Optional hint describing the element. This element is automatically associated
with the component's input element for optimal accessibility. | ReactNode | |
Controlled id. If omitted, a unique identifier will be automatically generated
for error, label, and hint accessibility. |
| |
attributes
applied to the input element. Use with caution. |
| {} |
Pass a ref to the input element. |
| |
Optional label describing the element. Recommended. This element is
automatically associated with the component's input element for optimal
accessibility. | ReactNode | |
Specifies the name for this input that’s submitted with the form. |
| |
An Event handler function. Fires when the input element loses focus. |
| |
Callback fired when the input value changes.
|
| |
Callback function triggered when the clear button is clicked.
|
| |
An Event handler function. Fires when the input element gains focus. |
| |
HTML placeholder attribute. |
| |
If true, the component is not editable by the user. |
| false |
Size of the element, label, hint, and error messages. When these properties
are supplied as templates, size styles are omitted. |
| |
lucide-react icon, positioned before the input. If supplied as a
LucideIcon , the size will automatically match the size prop.
Supply as a ReactElement for additional customization. https://lucide.dev |
| |
The style global attribute
contains CSS styling
declarations to be applied to the element. | CSSProperties | |
Controlled input value. |
|
Type
| ElementType| ComponentType
Default
'div'
Description
The component used for the root node. It can be a React component or
element.
Type
boolean
Description
If
true
, React will focus the component on mount.Type
string
Description
The className property of the Element
interface gets and sets the value of the
class attribute
of the specified element.
Type
boolean
Default
true
Description
If true, the component will render a clear icon which resets the
input field on click.
Type
| string| number| readonly string[]
Description
Default input value.
Type
boolean
Default
false
Description
If true, the component will not be interactive and will appear dimmed.
Type
| LucideIcon| ReactNode
Description
lucide-react icon, positioned after the input. If supplied as a
LucideIcon
, the size will automatically match the size prop.
Supply as a ReactElement
for additional customization. https://lucide.devType
ReactNode
Description
Optional error, triggers the invalid style variant if supplied. This element
is automatically associated with the component's input element for optimal
accessibility.
Type
string
Description
Specifies the id of the
<form>
this input belongs to. If omitted, it’s the
closest parent form.Type
boolean
Description
If true, the component will extend to fill the entire width of its parent
container.
Type
ReactNode
Description
Optional hint describing the element. This element is automatically associated
with the component's input element for optimal accessibility.
Type
string
Description
Controlled id. If omitted, a unique identifier will be automatically generated
for error, label, and hint accessibility.
Type
InputHTMLAttributes<HTMLInputElement>
Default
{}
Description
attributes
applied to the
input
element. Use with caution.Type
Ref<HTMLInputElement>
Description
Pass a ref to the input element.
Type
ReactNode
Description
Optional label describing the element. Recommended. This element is
automatically associated with the component's input element for optimal
accessibility.
Type
string
Description
Specifies the name for this input that’s submitted with the form.
Type
FocusEventHandler<HTMLInputElement>
Description
An Event handler function. Fires when the input element loses focus.
Type
(event: SyntheticEvent,value: T,reason:| 'input'| 'reset'| 'clear',) => void
Description
Callback fired when the input value changes.
- eventthe DOM event associated with the change.
- valuethe updated value.
- reasonthe cause of the change.
Type
(event: MouseEvent,) => void
Description
Callback function triggered when the clear button is clicked.
- eventthe DOM event associated with the change.
Type
FocusEventHandler<HTMLInputElement>
Description
An Event handler function. Fires when the input element gains focus.
Type
string
Description
HTML placeholder attribute.
Type
boolean
Default
false
Description
If true, the component is not editable by the user.
Type
| 's'| 'm'| 'l'
Description
Size of the element, label, hint, and error messages. When these properties
are supplied as templates, size styles are omitted.
Type
| LucideIcon| ReactNode
Description
lucide-react icon, positioned before the input. If supplied as a
LucideIcon
, the size will automatically match the size prop.
Supply as a ReactElement
for additional customization. https://lucide.devType
CSSProperties
Description
The style global attribute
contains CSS styling
declarations to be applied to the element.
Type
T
Description
Controlled input value.