Input

The Input component allows users to enter and edit text. It supports various styles, sizes, validation, and custom content.

Installation

$ cbui-cli install @crossbuildui/input

To get started, please make sure you have installed cbui-cli globally and authenticated your account. This will ensure you can access all the necessary features.

View documents

Import

index.tsx

import { Input } from '@/crossbuildui/input';
// import Icon from 'react-native-vector-icons/MaterialCommunityIcons'; // Or your preferred icon library for start/end content

Input Component

Basic Usage

A simple input field with a placeholder.

MyComponent.tsx

<Input placeholder="Enter your name" />

Variants

Inputs support multiple visual variant options: flat, bordered (default), faded, and underlined.

MyComponent.tsx

<View style={{gap: 16}}>
  <Input variant="flat" placeholder="Flat input" />
  <Input variant="bordered" placeholder="Bordered input (default)" />
  <Input variant="faded" placeholder="Faded input" />
  <Input variant="underlined" placeholder="Underlined input" />
</View>

Sizes

Adjust input size with sm, md (default), or lg.

MyComponent.tsx

<View style={{gap: 16}}>
  <Input size="sm" placeholder="Small input" label="Small" />
  <Input size="md" placeholder="Medium input (default)" label="Medium" />
  <Input size="lg" placeholder="Large input" label="Large" />
</View>

Radius

Control the border radius with none, sm, md (default), lg, or full.

MyComponent.tsx

<View style={{gap: 16}}>
  <Input radius="none" placeholder="No radius" />
  <Input radius="sm" placeholder="Small radius" />
  <Input radius="md" placeholder="Medium radius (default)" />
  <Input radius="lg" placeholder="Large radius" />
  <Input radius="full" placeholder="Full radius" startContent={<Icon name="magnify" size={18} />} />
</View>

Colors

The color prop influences the input's appearance on focus or when invalid. Supported colors include primary, secondary, success, warning, danger, and default.

MyComponent.tsx

<View style={{gap: 16}}>
  <Input label="Primary Focus" color="primary" placeholder="Focus to see color" />
  <Input label="Secondary Focus" color="secondary" placeholder="Focus to see color" />
  <Input label="Success Focus" color="success" placeholder="Focus to see color" />
  <Input label="Warning Focus" color="warning" placeholder="Focus to see color" />
  <Input label="Danger (Invalid)" color="danger" placeholder="Invalid state" isInvalid errorMessage="This field is invalid" />
  <Input label="Default Focus" color="default" placeholder="Focus to see color" />
</View>

Label and Description

Provide context to your input fields using the label and description props.

MyComponent.tsx

<View style={{gap: 16}}>
  <Input label="Email Address" placeholder="you@example.com" />
  <Input
    label="Password"
    placeholder="Enter your password"
    description="Must be at least 8 characters long."
    secureTextEntry
  />
</View>

Error Message & Validation

Display validation errors using isInvalid and errorMessage. Use the validate prop for built-in validation logic on blur.

MyComponent.tsx

// Controlled example for validation feedback
function ValidatedInput() {
  const [value, setValue] = React.useState("");
  const [error, setError] = React.useState("");

  const validateEmail = (email) => {
    if (!email) return "Email is required.";
    if (!/\S+@\S+\.\S+/.test(email)) return "Invalid email address.";
    return null;
  };

  const handleChange = (text) => {
    setValue(text);
    const validationError = validateEmail(text);
    setError(validationError);
  };

  return (
    <Input
      label="Validated Email"
      placeholder="Enter email"
      value={value}
      onChangeText={handleChange}
      isInvalid={!!error}
      errorMessage={error}
      // Or use the validate prop for onBlur validation:
      // validate={validateEmail}
    />
  );
}

// <ValidatedInput />

Start and End Content

Enhance inputs with icons or text elements using startContent and endContent.

MyComponent.tsx

<View style={{gap: 16}}>
  <Input
    placeholder="Search..."
    startContent={<Icon name="magnify" size={20} color="gray" />}
  />
  <Input
    placeholder="Amount"
    endContent={<Text style={{color: 'gray'}}>USD</Text>}
    keyboardType="numeric"
  />
  <Input
    placeholder="Website"
    startContent={<Text style={{color: 'gray'}}>https://</Text>}
    endContent={<Icon name="link-variant" size={20} color="gray" />}
  />
</View>

Controlled and Uncontrolled

Manage input state externally using value and onChangeText for a controlled component, or use defaultValue for an uncontrolled component.

MyComponent.tsx

// Controlled Input
function ControlledInputExample() {
  const [text, setText] = React.useState('');
  return (
    <Input
      value={text}
      onChangeText={setText}
      placeholder="Type something (controlled)"
      label="Controlled"
    />
  );
}

// Uncontrolled Input
<Input
  defaultValue="Initial text"
  placeholder="Type something (uncontrolled)"
  label="Uncontrolled"
/>

Disabled State

Disable the input using the disabled prop.

MyComponent.tsx

<Input placeholder="You can't type here" label="Disabled Input" disabled />

Props Overview

PROP	TYPE	DEFAULT	DESCRIPTION
`variant`	`InputVariant`	`'bordered'`	Visual style.
`color`	`InputColor`	`'default'`	Thematic color on focus/invalid.
`size`	`InputSize`	`'md'`	Size of the input.
`radius`	`InputRadius`	`'md'`	Border radius.
`label`	`ReactNode`	-	Label content for the input.
`description`	`ReactNode`	-	Helper text below the input.
`errorMessage`	`ReactNode`	-	Error message to display when `isInvalid`.
`isInvalid`	`boolean`	`false`	Marks input as invalid.
`validate`	`(value) => string \| null`	-	Validation function run on blur.
`startContent`	`ReactNode`	-	Content at the start of the input.
`endContent`	`ReactNode`	-	Content at the end of the input.
`styles`	`InputSlotsStyles`	-	Custom styles for slots (base, label, inputWrapper, etc.).
`style`	`StyleProp<ViewStyle>`	-	Style for the outermost container (`styles.base` equivalent).
`placeholderTextColor`	`ColorValue`	-	Custom color for placeholder text.
`disabled`	`boolean`	`false`	Disable the input.
`inputRef`	`React.Ref<TextInput>`	-	Ref for the underlying TextInput.
`value`	`string`	-	Controlled value of the input.
`defaultValue`	`string`	-	Initial value for uncontrolled input.
`...TextInputProps`	various	-	Other props from React Native's `TextInput`.

Styling

Customize the Input appearance using the style prop for the main wrapper or the styles prop for more granular control over internal slots:

style: Applied to the outermost container (View) of the entire input component. Equivalent to styles.base.
styles.base: Styles for the outermost container.
styles.label: Styles for the label Text component.
styles.inputWrapper: Styles for the View that wraps the actual TextInput and any start/end content.
styles.input: Styles for the TextInput element itself.
styles.description: Styles for the description Text component.
styles.errorMessage: Styles for the error message Text component.
styles.startContentWrapper: Styles for the View wrapping the startContent.
styles.endContentWrapper: Styles for the View wrapping the endContent.

MyComponent.tsx

<Input
  label="Custom Styled Input"
  placeholder="Enter details..."
  description="This input has custom slot styling."
  style={{ marginBottom: 20 }} // Styles the outermost 'base' container
  styles={{
    base: { backgroundColor: '#f0f8ff' },
    label: { color: 'navy', fontWeight: 'bold', fontStyle: 'italic' },
    inputWrapper: { borderColor: 'teal', borderWidth: 2, backgroundColor: 'white' },
    input: { color: 'purple', fontSize: 16 },
    description: { color: 'green', marginTop: 8 },
    errorMessage: { color: 'orange', fontWeight: 'bold' }
  }}
  startContent={<Icon name="pencil" size={20} color="teal" />}
/>

Accessibility

The Input component aims to be accessible:

The label prop is crucial for accessibility. It will be associated with the input field. If a visible label is not desired, ensure an accessibilityLabel is provided on the TextInput itself (passed via props).
When isInvalid is true and an errorMessage is provided, this information is available to assistive technologies.
Standard TextInput accessibility props like accessible, accessibilityLabel, accessibilityHint, etc., can be passed directly.

Checkbox InputOTP