TextBox API

Component status:: stable

Import

import { TextBox } from "@stratakit/bricks";
// OR
import * as TextBox from "@stratakit/bricks/TextBox";

TextBox.Root

Base element: <div>

Compound component for a text input. Allows adding additional decorations.

Example usage to add an end icon:

<TextBox.Root>
  <TextBox.Input defaultValue="Hello" />
  <TextBox.Icon href={...} />
</TextBox.Root>

Use with the Field components to automatically handle ID associations for labels and descriptions:

<Field.Root>
  <Field.Label>First name</Field.Label>
  <Field.Control
    render={(controlProps) => (
      <TextBox.Root>
        <TextBox.Input name="firstName" {...controlProps} />
        <TextBox.Icon href={…} />
      </TextBox.Root>
    )}
  />
</Field.Root>

Additional props

render

TextBox.Input

Base element: <input>

An input component that allows users to enter text based values.

Example usage:

<TextBox.Input name="greeting" defaultValue="Hello" />

To add additional decorations, see TextBox.Root component.

Use with the Field components to automatically handle ID associations for labels and descriptions:

<Field.Root>
  <Field.Label>First name</Field.Label>
  <Field.Control render={<TextBox.Input name="firstName" />} />
</Field.Root>

Without the Field components you will need to manually associate labels, descriptions, etc.:

<Label htmlFor="fruit">Fruit</Label>
<TextBox.Input id="fruit" aria-describedby="fruit-description" />
<Description id="fruit-description">Something to include in a fruit salad.</Description>

Underneath, it’s an HTML input, i.e. <input>, so it supports the same props, including value, defaultValue, onChange, and disabled.

For a multiline text input, use the TextBox.Textarea component.

accessibleWhenDisabled

Type: boolean | undefined (optional)

Indicates whether the element should be focusable even when it is disabled.

This is important when discoverability is a concern. For example:

A toolbar in an editor contains a set of special smart paste functions that are disabled when the clipboard is empty or when the function is not applicable to the current content of the clipboard. It could be helpful to keep the disabled buttons focusable if the ability to discover their functionality is primarily via their presence on the toolbar.

Learn more on Focusability of disabled controls.

autoFocus

Type: boolean | undefined (optional)

Default: false

Automatically focuses the element upon mounting, similar to the native autoFocus prop. This addresses an issue where the element with the native autoFocus attribute might receive focus before React effects are executed.

The autoFocus prop can also be used with Focusable elements within a Dialog component, establishing the initial focus as the dialog opens.

Note: For this prop to work, the focusable prop must be set to true, if it’s not set by default.

children

Type: undefined (optional)

Input is a void element and no content is permitted.

disabled

Type: boolean | undefined (optional)

Default: false

Determines if the element is disabled. This sets the aria-disabled attribute accordingly, enabling support for all elements, including those that don’t support the native disabled attribute.

This feature can be combined with the accessibleWhenDisabled prop to make disabled elements still accessible via keyboard.

Note: For this prop to work, the focusable prop must be set to true, if it’s not set by default.

render

Type: (props: P) => React.ReactNode | React.ReactElement | undefined (optional)

Allows the component to be rendered as a different HTML element or React component. The value can be a React element or a function that takes in the original component props and gives back a React element with the props merged.

Check out the Composition guide for more details.

type

Type: any (optional)

Default: "text"

Describes a text based input type based on the value type the user will enter.

TextBox.Textarea

Base element: <textarea>

A styled textarea element that allows users to enter multiline text values.

Example usage:

<TextBox.Textarea defaultValue="Hello" />

Use with the Field components to automatically handle ID associations for labels and descriptions:

<Field.Root>
  <Field.Label>Leave a comment, be kind</Field.Label>
  <Field.Control render={<TextBox.Textarea name="comment" />} />
</Field.Root>

Without the Field components you will need to manually associate labels, descriptions, etc.:

<Label htmlFor="fruit">Fruit</Label>
<TextBox.Input id="fruit" aria-describedby="fruit-description" />
<Description id="fruit-description">Something to include in a fruit salad.</Description>

Underneath, it’s an HTML textarea, i.e. <textarea>, so it supports the same props, including value, defaultValue, onChange, and disabled.

Additional props

TextBox.Icon

Base element: <svg>

A static icon decoration for the TextBox.Root component. Can be added before or after the TextBox.Input.

alt

Type: string | undefined (optional)

Alternative text describing the icon.

When this prop is passed, the SVG gets rendered as role="img" and labelled using the provided text.

This prop is not required if the icon is purely decorative. By default, the icon will be hidden from the accessibility tree.

href

Type: string | undefined (optional)

URL of the .svg file (e.g. from @stratakit/icons).

The URL can contain a hash pointing to a specific symbol within the SVG (e.g. #icon, #icon-large). By default, the #icon symbol is used if no hash is provided.

Note: The .svg must be an external HTTP resource for it to be processed by the <use> element. As a fallback, JS will be used to fetch the SVG from non-supported URLs; the fetched SVG content will be sanitized using the unstable_htmlSanitizer function passed to <Root>.

key

Type: Key | null | undefined (optional)

ref

Type: Ref<HTMLElement | SVGSVGElement> | undefined (optional)

Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref).

render

Type: (props: P) => React.ReactNode | React.ReactElement | undefined (optional)

Check out the Composition guide for more details.

size

Type: "large" | "regular" | undefined (optional)

Size of the icon. This only affects the icon’s physical dimensions (not the SVG contents).

Defaults to "regular" (16px) and can be optionally set to "large" (24px).

TextBox.Text

Base element: <span>

A static text decoration for the TextBox.Root component. Can be added before or after the TextBox.Input.

Additional props

render