syncfusion-react-textbox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React TextBox Component

实现Syncfusion React TextBox组件

The TextBox component is a lightweight input control that captures user text input with support for floating labels, validation states, icons, and advanced features. This skill guides you through implementing, configuring, and customizing the TextBox component in React applications.

TextBox组件是一款轻量级输入控件，可采集用户文本输入，支持浮动标签、校验状态、图标等高级特性。本指南将介绍如何在React应用中实现、配置和自定义TextBox组件。

Navigation Guide

导航指南

🛑 Agentic use: Do not execute multiple steps autonomously. Confirm with the user before each action (install, run, file creation).

🛑 Agent使用说明： 请勿自主执行多步操作，每次执行安装、运行、文件创建等操作前都需要先向用户确认。

Getting Started

入门指南

📄 Read: references/getting-started.md

Vite setup for React development
Installing
```
@syncfusion/ej2-react-inputs
```
package 🛑 STOP — Do not install packages autonomously. Ask the user to run:
npm install @syncfusion/ej2-react-inputs
. Pin a specific version (e.g.,
@syncfusion/ej2-react-inputs@28.x.x
) and verify with
npm audit
Adding CSS imports and themes
Creating your first TextBox component
Adding icons and floating labels
Running the development server 🛑 STOP — Do not start the dev server autonomously. Ask the user to run:
npm run dev

📄 阅读： references/getting-started.md

React开发的Vite环境搭建
安装
```
@syncfusion/ej2-react-inputs
```
包 🛑 停止 — 请勿自主安装包，告知用户运行命令：
npm install @syncfusion/ej2-react-inputs
，固定指定版本（例如
@syncfusion/ej2-react-inputs@28.x.x
）并通过
npm audit
校验
引入CSS和主题
创建你的第一个TextBox组件
添加图标和浮动标签
运行开发服务器 🛑 停止 — 请勿自主启动开发服务器，告知用户运行命令：
npm run dev

Features and Groups

特性与功能组

📄 Read: references/features-and-groups.md

Floating label behavior (Never, Always, Auto)
Icons with
```
addIcon()
```
method (prepend/append)
Clear button with
```
showClearButton
```
property
Rounded corner with
```
e-corner
```
CSS class
Disabled state with
```
enabled={false}
```
Multi-line textbox creation
TextBox with clear button and floating label combinations

📄 阅读： references/features-and-groups.md

浮动标签行为（永不显示、始终显示、自动）
通过
```
addIcon()
```
方法添加图标（前置/后置）
通过
```
showClearButton
```
属性启用清除按钮
通过
```
e-corner
```
CSS类实现圆角效果
通过
```
enabled={false}
```
设置禁用状态
创建多行文本框
同时支持清除按钮和浮动标签的TextBox组合

Styling and Sizing

样式与尺寸配置

📄 Read: references/styling-and-sizing.md

Three predefined sizes: Normal, Small (
```
e-small
```
), Large (
```
e-bigger
```
)
Applying size classes via
```
cssClass
```
property
Rounded corner with
```
e-corner
```
CSS class
CSS customization for TextBox wrapper and floating label
Custom CSS classes and themes
Responsive design patterns

📄 阅读： references/styling-and-sizing.md

三种预设尺寸：普通、小尺寸（
```
e-small
```
）、大尺寸（
```
e-bigger
```
）
通过
```
cssClass
```
属性应用尺寸类
通过
```
e-corner
```
CSS类实现圆角效果
自定义TextBox容器和浮动标签的CSS样式
自定义CSS类和主题
响应式设计模式

Multiline TextBox

多行文本框

📄 Read: references/multiline-textbox.md

Creating multiline/textarea inputs with
```
multiline={true}
```
Floating labels with multiline
Auto-resizing textboxes
Disabling resize functionality
Limiting text length with
```
htmlAttributes={{ maxlength: '...' }}
```
Character counting and display

📄 阅读： references/multiline-textbox.md

通过
```
multiline={true}
```
创建多行/textarea输入框
多行文本框支持浮动标签
自适应高度文本框
禁用调整尺寸功能
通过
```
htmlAttributes={{ maxlength: '...' }}
```
限制文本长度
字符计数与展示

Validation and States

校验与状态

📄 Read: references/validation-and-states.md

Error, warning, and success validation states via
```
cssClass
```
Applying validation classes (
```
e-error
```
,
```
e-warning
```
,
```
e-success
```
)
Disabled state with
```
enabled={false}
```
(not
```
disabled
```
)
Read-only state with
```
readonly={true}
```
Differences between disabled and read-only
Dynamic color changes based on values using
```
input
```
event

📄 阅读： references/validation-and-states.md

通过
```
cssClass
```
配置错误、警告、成功校验状态
应用校验类（
```
e-error
```
、
```
e-warning
```
、
```
e-success
```
）
通过
```
enabled={false}
```
设置禁用状态（而非
```
disabled
```
）
通过
```
readonly={true}
```
设置只读状态
禁用状态和只读状态的区别
通过
```
input
```
事件根据输入值动态修改颜色

Advanced Features

高级特性

📄 Read: references/advanced-features.md

Adornments:
```
prependTemplate
```
and
```
appendTemplate
```
properties
Interactive adornments (password toggle, delete button)
React functional components with hooks
```
useState
```
,
```
useEffect
```
,
```
useRef
```
,
```
useReducer
```
integration
Event handling (created, input, change events)
Form validation patterns

📄 阅读： references/advanced-features.md

装饰元素：
```
prependTemplate
```
和
```
appendTemplate
```
属性
交互性装饰元素（密码可见性切换、删除按钮）
结合Hooks的React函数式组件实现
```
useState
```
、
```
useEffect
```
、
```
useRef
```
、
```
useReducer
```
集成
事件处理（created、input、change事件）
表单校验模式

Accessibility and Migration

无障碍与迁移

📄 Read: references/accessibility-and-migration.md

WCAG 2.2, Section 508, and WAI-ARIA compliance
Screen reader support and ARIA attributes
Right-to-Left (RTL) support with
```
enableRtl
```
property
Keyboard navigation support
Migrating from CSS TextBox to React component
Before/after code comparison

📄 阅读： references/accessibility-and-migration.md

符合WCAG 2.2、Section 508和WAI-ARIA标准
屏幕阅读器支持与ARIA属性
通过
```
enableRtl
```
属性支持从右到左（RTL）显示
键盘导航支持
从CSS TextBox迁移到React组件
迁移前后代码对比

API Reference

API参考

📄 Read: references/api.md

All properties:

placeholder

floatLabelType

value

type

cssClass

multiline

showClearButton

enabled

readonly

enableRtl

enablePersistence

autocomplete

htmlAttributes

locale

width

prependTemplate

appendTemplate

Methods:

addIcon

addAttributes

removeAttributes

focusIn

focusOut

destroy

getPersistData

Events:
```
created
```
,
```
destroyed
```
,
```
change
```
,
```
input
```
,
```
focus
```
,
```
blur
```

📄 阅读： references/api.md

所有属性：

placeholder

、

floatLabelType

、

value

、

type

、

cssClass

、

multiline

、

showClearButton

、

enabled

、

readonly

、

enableRtl

、

enablePersistence

、

autocomplete

、

htmlAttributes

、

locale

、

width

、

prependTemplate

、

appendTemplate

方法：

addIcon

、

addAttributes

、

removeAttributes

、

focusIn

、

focusOut

、

destroy

、

getPersistData

事件：
```
created
```
、
```
destroyed
```
、
```
change
```
、
```
input
```
、
```
focus
```
、
```
blur
```

Quick Start

快速开始

Basic TextBox with Floating Label

带浮动标签的基础TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import './App.css';

export default function App() {
  return (
    <TextBoxComponent 
      placeholder="Enter your name" 
      floatLabelType="Auto"
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import './App.css';

export default function App() {
  return (
    <TextBoxComponent 
      placeholder="Enter your name" 
      floatLabelType="Auto"
    />
  );
}

TextBox with Icon

带图标的TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useRef } from 'react';

export default function App() {
  const textboxRef = useRef(null);

  const handleCreate = () => {
    if (textboxRef.current) {
      textboxRef.current.addIcon('append', 'e-icons e-input-popup-date');
    }
  };

  return (
    <TextBoxComponent
      placeholder="Enter date"
      floatLabelType="Auto"
      ref={textboxRef}
      created={handleCreate}
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useRef } from 'react';

export default function App() {
  const textboxRef = useRef(null);

  const handleCreate = () => {
    if (textboxRef.current) {
      textboxRef.current.addIcon('append', 'e-icons e-input-popup-date');
    }
  };

  return (
    <TextBoxComponent
      placeholder="Enter date"
      floatLabelType="Auto"
      ref={textboxRef}
      created={handleCreate}
    />
  );
}

TextBox with Clear Button

带清除按钮的TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function App() {
  return (
    <TextBoxComponent
      placeholder="Enter your email"
      floatLabelType="Auto"
      showClearButton={true}
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function App() {
  return (
    <TextBoxComponent
      placeholder="Enter your email"
      floatLabelType="Auto"
      showClearButton={true}
    />
  );
}

Multiline TextBox

多行TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function App() {
  return (
    <TextBoxComponent
      multiline={true}
      placeholder="Enter your address"
      floatLabelType="Auto"
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function App() {
  return (
    <TextBoxComponent
      multiline={true}
      placeholder="Enter your address"
      floatLabelType="Auto"
    />
  );
}

Common Patterns

常用场景

Form with Validation States

带校验状态的表单

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';

export default function ValidationForm() {
  const [cssClass, setCssClass] = useState('');

  return (
    <div>
      <TextBoxComponent
        placeholder="Enter username"
        cssClass={cssClass}
        floatLabelType="Auto"
        input={(e: any) => {
          if (!e.value) setCssClass('');
          else if (e.value.length < 3) setCssClass('e-error');
          else if (e.value.length < 6) setCssClass('e-warning');
          else setCssClass('e-success');
        }}
      />
    </div>
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useState } from 'react';

export default function ValidationForm() {
  const [cssClass, setCssClass] = useState('');

  return (
    <div>
      <TextBoxComponent
        placeholder="Enter username"
        cssClass={cssClass}
        floatLabelType="Auto"
        input={(e: any) => {
          if (!e.value) setCssClass('');
          else if (e.value.length < 3) setCssClass('e-error');
          else if (e.value.length < 6) setCssClass('e-warning');
          else setCssClass('e-success');
        }}
      />
    </div>
  );
}

Password TextBox with Toggle

带可见性切换的密码输入框

tsx

import * as React from 'react';
import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useRef, useState } from 'react';

export default function PasswordInput() {
  const textboxRef = useRef<TextBoxComponent>(null);
  const [isVisible, setIsVisible] = useState(false);

  const toggleVisibility = () => {
    if (textboxRef.current) {
      const newVisibility = !isVisible;
      textboxRef.current.type = newVisibility ? 'text' : 'password';
      setIsVisible(newVisibility);
    }
  };

  function appendTemplate(): JSX.Element {
    return (
      <>
        <span className="e-input-separator"></span>
        <span
          className={`e-icons ${isVisible ? 'e-eye-slash' : 'e-eye'}`}
          onClick={toggleVisibility}
          style={{ cursor: 'pointer' }}
        ></span>
      </>
    );
  }

  return (
    <TextBoxComponent
      ref={textboxRef}
      type="password"
      placeholder="Enter password"
      floatLabelType="Auto"
      appendTemplate={appendTemplate}
    />
  );
}

tsx

import * as React from 'react';
import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useRef, useState } from 'react';

export default function PasswordInput() {
  const textboxRef = useRef<TextBoxComponent>(null);
  const [isVisible, setIsVisible] = useState(false);

  const toggleVisibility = () => {
    if (textboxRef.current) {
      const newVisibility = !isVisible;
      textboxRef.current.type = newVisibility ? 'text' : 'password';
      setIsVisible(newVisibility);
    }
  };

  function appendTemplate(): JSX.Element {
    return (
      <>
        <span className="e-input-separator"></span>
        <span
          className={`e-icons ${isVisible ? 'e-eye-slash' : 'e-eye'}`}
          onClick={toggleVisibility}
          style={{ cursor: 'pointer' }}
        ></span>
      </>
    );
  }

  return (
    <TextBoxComponent
      ref={textboxRef}
      type="password"
      placeholder="Enter password"
      floatLabelType="Auto"
      appendTemplate={appendTemplate}
    />
  );
}

Email Input with Unit Label

带单位标签的邮箱输入框

tsx

import * as React from 'react';
import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function EmailInput() {
  function prependTemplate(): JSX.Element {
    return (
      <>
        <span className="e-icons e-user"></span>
        <span className="e-input-separator"></span>
      </>
    );
  }

  function appendTemplate(): JSX.Element {
    return (
      <>
        <span className="e-input-separator"></span>
        <span>.com</span>
      </>
    );
  }

  return (
    <TextBoxComponent
      type="email"
      placeholder="Enter email"
      floatLabelType="Auto"
      prependTemplate={prependTemplate}
      appendTemplate={appendTemplate}
    />
  );
}

tsx

import * as React from 'react';
import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function EmailInput() {
  function prependTemplate(): JSX.Element {
    return (
      <>
        <span className="e-icons e-user"></span>
        <span className="e-input-separator"></span>
      </>
    );
  }

  function appendTemplate(): JSX.Element {
    return (
      <>
        <span className="e-input-separator"></span>
        <span>.com</span>
      </>
    );
  }

  return (
    <TextBoxComponent
      type="email"
      placeholder="Enter email"
      floatLabelType="Auto"
      prependTemplate={prependTemplate}
      appendTemplate={appendTemplate}
    />
  );
}

Rounded Corner TextBox

圆角TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function RoundedCornerTextBox() {
  return (
    <TextBoxComponent
      placeholder="Enter Date"
      cssClass="e-corner"
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function RoundedCornerTextBox() {
  return (
    <TextBoxComponent
      placeholder="Enter Date"
      cssClass="e-corner"
    />
  );
}

Disabled TextBox

禁用状态TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function DisabledTextBox() {
  return (
    <TextBoxComponent
      placeholder="Enter Name"
      enabled={false}
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function DisabledTextBox() {
  return (
    <TextBoxComponent
      placeholder="Enter Name"
      enabled={false}
    />
  );
}

RTL TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function RTLTextBox() {
  return (
    <TextBoxComponent
      placeholder="أدخل اسمك"
      floatLabelType="Auto"
      enableRtl={true}
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';

export default function RTLTextBox() {
  return (
    <TextBoxComponent
      placeholder="أدخل اسمك"
      floatLabelType="Auto"
      enableRtl={true}
    />
  );
}

Auto-sizing Multiline TextBox

自适应高度多行TextBox

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useRef } from 'react';

export default function AutoSizeTextbox() {
  const textboxRef = useRef(null);

  const handleInput = () => {
    if (textboxRef.current) {
      const elem = textboxRef.current.respectiveElement;
      elem.style.height = 'auto';
      elem.style.height = elem.scrollHeight + 'px';
    }
  };

  const handleCreate = () => {
    if (textboxRef.current) {
      textboxRef.current.addAttributes({ rows: 1 });
    }
    handleInput();
  };

  return (
    <TextBoxComponent
      multiline={true}
      placeholder="Enter your message"
      floatLabelType="Auto"
      ref={textboxRef}
      created={handleCreate}
      input={handleInput}
    />
  );
}

tsx

import { TextBoxComponent } from '@syncfusion/ej2-react-inputs';
import { useRef } from 'react';

export default function AutoSizeTextbox() {
  const textboxRef = useRef(null);

  const handleInput = () => {
    if (textboxRef.current) {
      const elem = textboxRef.current.respectiveElement;
      elem.style.height = 'auto';
      elem.style.height = elem.scrollHeight + 'px';
    }
  };

  const handleCreate = () => {
    if (textboxRef.current) {
      textboxRef.current.addAttributes({ rows: 1 });
    }
    handleInput();
  };

  return (
    <TextBoxComponent
      multiline={true}
      placeholder="Enter your message"
      floatLabelType="Auto"
      ref={textboxRef}
      created={handleCreate}
      input={handleInput}
    />
  );
}

Key Properties

核心属性

Property	Type	Purpose
`placeholder`	`string`	Hint text shown when input is empty
`floatLabelType`	`"Never" \| "Always" \| "Auto"`	Label animation behavior
`value`	`string`	Sets the content of the TextBox
`type`	`string`	Input type ( `text` , `password` , `email` , `number` , etc.)
`multiline`	`boolean`	Convert to textarea for multi-line input
`showClearButton`	`boolean`	Display clear button when input has value
`cssClass`	`string`	Apply CSS classes for sizing/validation/appearance (e.g., `"e-error"` , `"e-small"` , `"e-corner"` )
`enabled`	`boolean`	Enable ( `true` ) or disable ( `false` ) input interaction
`readonly`	`boolean`	Allow selection but prevent editing
`enableRtl`	`boolean`	Enable right-to-left rendering
`enablePersistence`	`boolean`	Persist value state between page reloads ⚠️ Stores data in browser storage — enable only with explicit user consent
`autocomplete`	`string`	Control browser autocomplete ( `"on"` \| `"off"` )
`htmlAttributes`	`{ [key: string]: string }`	Pass additional HTML attributes (e.g., `{ maxlength: '200' }` )
`locale`	`string`	Override global culture/localization value
`width`	`number \| string`	Set component width
`prependTemplate`	`() => JSX.Element`	Render element before input
`appendTemplate`	`() => JSX.Element`	Render element after input

属性	类型	用途
`placeholder`	`string`	输入框为空时显示的提示文本
`floatLabelType`	`"Never" \| "Always" \| "Auto"`	标签动画行为
`value`	`string`	设置TextBox的内容
`type`	`string`	输入框类型（ `text` 、 `password` 、 `email` 、 `number` 等）
`multiline`	`boolean`	转换为textarea实现多行输入
`showClearButton`	`boolean`	输入框有值时显示清除按钮
`cssClass`	`string`	应用CSS类实现尺寸/校验/外观定制（例如 `"e-error"` 、 `"e-small"` 、 `"e-corner"` ）
`enabled`	`boolean`	启用（ `true` ）或禁用（ `false` ）输入交互
`readonly`	`boolean`	允许选中但禁止编辑
`enableRtl`	`boolean`	启用从右到左渲染
`enablePersistence`	`boolean`	页面重载间保留值状态 ⚠️ 数据存储在浏览器缓存中 — 仅在获得用户明确同意后启用
`autocomplete`	`string`	控制浏览器自动填充（ `"on"` \| `"off"` ）
`htmlAttributes`	`{ [key: string]: string }`	传递额外HTML属性（例如 `{ maxlength: '200' }` ）
`locale`	`string`	覆盖全局文化/本地化配置
`width`	`number \| string`	设置组件宽度
`prependTemplate`	`() => JSX.Element`	在输入框前渲染元素
`appendTemplate`	`() => JSX.Element`	在输入框后渲染元素

Key Events

核心事件

Event	Arguments	Purpose
`created`	`Object`	Fires after component initialization
`destroyed`	`Object`	Fires when component is destroyed
`change`	`ChangedEventArgs`	Fires when value changes on focus-out
`input`	`InputEventArgs`	Fires on every keystroke
`focus`	`FocusInEventArgs`	Fires when TextBox gains focus
`blur`	`FocusOutEventArgs`	Fires when TextBox loses focus

事件	参数	用途
`created`	`Object`	组件初始化完成后触发
`destroyed`	`Object`	组件销毁时触发
`change`	`ChangedEventArgs`	输入框失焦且值发生变化时触发
`input`	`InputEventArgs`	每次按键输入时触发
`focus`	`FocusInEventArgs`	TextBox获得焦点时触发
`blur`	`FocusOutEventArgs`	TextBox失去焦点时触发

syncfusion-react-textbox

Original

Translation

Implementing Syncfusion React TextBox Component

实现Syncfusion React TextBox组件

Navigation Guide

导航指南

Getting Started

入门指南

Features and Groups

特性与功能组

Styling and Sizing

样式与尺寸配置

Multiline TextBox

多行文本框

Validation and States

校验与状态

Advanced Features

高级特性

Accessibility and Migration

无障碍与迁移

API Reference

API参考

Quick Start

快速开始

Basic TextBox with Floating Label

带浮动标签的基础TextBox

TextBox with Icon

带图标的TextBox

TextBox with Clear Button

带清除按钮的TextBox

Multiline TextBox

多行TextBox

Common Patterns

常用场景

Form with Validation States

带校验状态的表单

Password TextBox with Toggle

带可见性切换的密码输入框

Email Input with Unit Label

带单位标签的邮箱输入框

Rounded Corner TextBox

圆角TextBox

Disabled TextBox

禁用状态TextBox

RTL TextBox

RTL TextBox

Auto-sizing Multiline TextBox

自适应高度多行TextBox

Key Properties

核心属性

Key Events

核心事件

Related Documentation

相关文档