Text Field Textarea

여러 줄의 긴 텍스트를 입력받고 자동으로 높이를 조절하는 컴포넌트입니다.

사용 가능 버전@seed-design/[email protected], @seed-design/[email protected]

Installation

npx @seed-design/cli add ui:text-field

pnpm dlx @seed-design/cli add ui:text-field

yarn dlx @seed-design/cli add ui:text-field

bun x @seed-design/cli add ui:text-field

의존성 설치

npm install @seed-design/lynx-react

yarn add @seed-design/lynx-react

pnpm add @seed-design/lynx-react

bun add @seed-design/lynx-react

아래 코드를 복사 후 붙여넣고 사용하세요

/**
 * @file ui:text-field
 * @requires @seed-design/lynx-react@>=0.1.0 <1.0.0
 * @requires @seed-design/lynx-css@>=0.1.0 <1.0.0
 **/

import * as React from "@lynx-js/react";
import {
  Field as SeedField,
  TextField as SeedTextField,
  type UseTextFieldWithGraphemesParams,
  useTextFieldWithGraphemes,
} from "@seed-design/lynx-react";

type TextFieldRootRef = React.ComponentRef<typeof SeedTextField.Root>;
type FieldRootRef = React.ComponentRef<typeof SeedField.Root>;

export interface TextFieldProps
  extends Omit<SeedTextField.RootProps, "children" | "onValueChange"> {
  children?: React.ReactNode;
  label?: React.ReactNode;
  labelWeight?: SeedField.LabelProps["weight"];
  indicator?: React.ReactNode;
  prefixIcon?: SeedTextField.PrefixIconProps["icon"];
  prefix?: React.ReactNode;
  suffixIcon?: SeedTextField.SuffixIconProps["icon"];
  suffix?: React.ReactNode;
  description?: React.ReactNode;
  errorMessage?: React.ReactNode;
  hideCharacterCount?: boolean;
  maxGraphemeCount?: number;
  showRequiredIndicator?: boolean;
  fieldRef?: React.Ref<FieldRootRef>;
  onValueChange?: UseTextFieldWithGraphemesParams["onValueChange"];
}

/**
 * @see https://seed-design.io/lynx/components/text-field-input
 */
export const TextField = React.forwardRef<TextFieldRootRef, TextFieldProps>(
  (
    {
      children,
      label,
      labelWeight,
      indicator,
      prefixIcon,
      prefix,
      suffixIcon,
      suffix,
      description,
      errorMessage,
      hideCharacterCount,
      maxGraphemeCount,
      showRequiredIndicator,
      fieldRef,
      value,
      defaultValue,
      onValueChange,
      required,
      disabled,
      invalid,
      readOnly,
      name,
      ...rootProps
    },
    ref,
  ) => {
    const { textFieldRootProps, counterProps } = useTextFieldWithGraphemes({
      value,
      defaultValue,
      onValueChange,
      maxGraphemeCount,
    });
    const renderHeader = label != null || indicator != null;
    const renderDescription = description != null && !(invalid && errorMessage != null);
    const renderErrorMessage = invalid && errorMessage != null;
    const renderCharacterCount = !hideCharacterCount && maxGraphemeCount !== undefined;
    const renderFooter = renderDescription || renderErrorMessage || renderCharacterCount;

    return (
      <SeedField.Root
        ref={fieldRef}
        required={required}
        disabled={disabled}
        invalid={invalid}
        readOnly={readOnly}
      >
        {renderHeader ? (
          <SeedField.Header>
            <SeedField.Label weight={labelWeight}>
              {label}
              {showRequiredIndicator ? <SeedField.RequiredIndicator /> : null}
              {indicator != null ? (
                <SeedField.IndicatorText>{indicator}</SeedField.IndicatorText>
              ) : null}
            </SeedField.Label>
          </SeedField.Header>
        ) : null}
        <SeedTextField.Root ref={ref} name={name} {...rootProps} {...textFieldRootProps}>
          {prefixIcon ? <SeedTextField.PrefixIcon icon={prefixIcon} /> : null}
          {prefix != null ? <SeedTextField.PrefixText>{prefix}</SeedTextField.PrefixText> : null}
          {children}
          {suffix != null ? <SeedTextField.SuffixText>{suffix}</SeedTextField.SuffixText> : null}
          {suffixIcon ? <SeedTextField.SuffixIcon icon={suffixIcon} /> : null}
        </SeedTextField.Root>
        {renderFooter ? (
          <SeedField.Footer>
            {renderDescription ? (
              <SeedField.Description>{description}</SeedField.Description>
            ) : null}
            {renderErrorMessage ? (
              <SeedField.ErrorMessage>{errorMessage}</SeedField.ErrorMessage>
            ) : null}
            {renderCharacterCount ? <SeedField.CharacterCount {...counterProps} /> : null}
          </SeedField.Footer>
        ) : null}
      </SeedField.Root>
    );
  },
);
TextField.displayName = "TextField";

export interface TextFieldInputProps extends SeedTextField.InputProps {}

/**
 * @see https://seed-design.io/lynx/components/text-field-input
 */
export const TextFieldInput = SeedTextField.Input;

export interface TextFieldTextareaProps extends SeedTextField.TextareaProps {}

/**
 * @see https://seed-design.io/lynx/components/text-field-textarea
 */
export const TextFieldTextarea = SeedTextField.Textarea;

/**
 * This file is a snippet from SEED Design, helping you get started quickly with @seed-design/* packages.
 * You can extend this snippet however you want.
 */

Props

`TextField`

Prop

Type

children?React.ReactNode

label?React.ReactNode

labelWeight?"medium" | "bold" | undefined

indicator?React.ReactNode

prefixIcon?React.ReactElement<LynxIconElementProps, string | React.JSXElementConstructor<any>> | undefined

prefix?React.ReactNode

suffixIcon?React.ReactElement<LynxIconElementProps, string | React.JSXElementConstructor<any>> | undefined

suffix?React.ReactNode

description?React.ReactNode

errorMessage?React.ReactNode

hideCharacterCount?boolean | undefined

maxGraphemeCount?number | undefined

showRequiredIndicator?boolean | undefined

fieldRef?React.Ref<NodesRef> | undefined

onValueChange?((values: { value: string; graphemes: string[]; slicedValue: string; slicedGraphemes: string[]; }) => void) | undefined

value?string | undefined

defaultValue?string | undefined

required?boolean | undefined

name?string | undefined

style?CSSProperties | undefined

className?string | undefined

`TextFieldTextarea`

Prop

Type

placeholder?string | undefined

maxlength?number | undefined

maxlines?number | undefined

bounces?boolean | undefined

readonly?boolean | undefined

disabled?boolean | undefined

show-soft-input-on-focus?boolean | undefined

input-filter?string | undefined

enable-scroll-bar?boolean | undefined

ios-auto-correct?boolean | undefined

ios-spell-check?boolean | undefined

bindfocus?((e: BaseEvent<"bindfocus", TextAreaFocusEvent>) => void) | undefined

bindblur?((e: BaseEvent<"bindblur", TextAreaBlurEvent>) => void) | undefined

bindconfirm?((e: BaseEvent<"bindconfirm", TextAreaConfirmEvent>) => void) | undefined

bindinput?((e: BaseEvent<"bindinput", TextAreaInputEvent>) => void) | undefined

bindselection?((e: BaseEvent<"bindselection", TextAreaSelectionChangeEvent>) => void) | undefined

id?string | undefined

name?string | undefined

hidden?boolean | undefined

flatten?boolean | undefined

focusable?boolean | undefined

bindlayoutchange?EventHandler<LayoutChangeDetailEvent<Target>> | undefined

main-thread:bindlayoutchange?EventHandler<LayoutChangeDetailEvent<Element>> | undefined

style?CSSProperties | undefined

className?string | undefined

Usage

Snippet의 TextField가 label, description, required indicator와 여러 줄 입력 영역을 조합합니다. Lynx에는 HTML label for 연결이 없으므로 native 입력에는 accessibility-label을 함께 지정합니다.

import { TextField, TextFieldTextarea } from "@/components/ui/text-field";

export function IntroductionField() {
  return (
    <TextField label="소개">
      <TextFieldTextarea accessibility-label="소개" placeholder="소개를 입력해 주세요" />
    </TextField>
  );
}

Controlled value

value와 onValueChange를 전달하면 controlled mode로 동작합니다. Lynx native textarea에는 value attribute가 없으므로 컴포넌트가 setValue UI method로 값을 동기화합니다.

import { useState } from "@lynx-js/react";
import { TextField, TextFieldTextarea } from "@/components/ui/text-field";

export function ControlledIntroduction() {
  const [value, setValue] = useState("");

  return (
    <TextField value={value} onValueChange={({ value }) => setValue(value)}>
      <TextFieldTextarea accessibility-label="소개" />
    </TextField>
  );
}

TextFieldTextarea는 기본적으로 native textarea의 intrinsic height를 사용해 내용에 맞춰 높이가 늘어납니다. iOS에서는 wrapper가, Android에서는 native textarea가 최소 높이와 세로 여백을 담당합니다. 실제 wrapper 높이가 달라질 때만 Keyboard Avoiding 위치를 다시 계산합니다. 고정 높이가 필요하면 autoresize={false}와 명시적인 height를 함께 사용합니다.

Android에서는 SEED typography의 줄 높이를 맞추기 위해 line-spacing="3.2px"를 기본 적용합니다. line-spacing을 명시하면 모든 플랫폼에서 해당 값이 우선하며, Android의 기본 보정은 line-spacing={0}으로 해제할 수 있습니다. fontSize나 lineHeight를 직접 변경한다면 이에 맞는 line-spacing도 함께 지정해야 합니다.

<TextField label="소개">
  <TextFieldTextarea accessibility-label="소개" placeholder="소개를 입력해 주세요" />
</TextField>

Grapheme limit

이모지·조합 문자를 사용자에게 보이는 한 글자로 계산하려면 snippet의 maxGraphemeCount와 onValueChange를 사용합니다.

import { useState } from "@lynx-js/react";
import { TextField, TextFieldTextarea } from "@/components/ui/text-field";

export function LimitedIntroductionField() {
  const [value, setValue] = useState("");

  return (
    <TextField
      label="소개"
      value={value}
      maxGraphemeCount={80}
      onValueChange={({ slicedValue }) => setValue(slicedValue)}
    >
      <TextFieldTextarea accessibility-label="소개" />
    </TextField>
  );
}

Keyboard avoidance

KeyboardAvoidingScrollView 안에 배치하면 TextFieldTextarea가 focus될 때 자동으로 등록됩니다. autoresize로 레이아웃이 바뀌면 활성 입력 위치를 다시 계산합니다.

import { KeyboardAvoidingScrollView } from "@seed-design/lynx-react";
import { TextField, TextFieldTextarea } from "@/components/ui/text-field";

export function Form() {
  return (
    <KeyboardAvoidingScrollView>
      <TextField label="내용">
        <TextFieldTextarea accessibility-label="내용" />
      </TextField>
    </KeyboardAvoidingScrollView>
  );
}

Web Version Differences

편집 가능한 상태에서는 HTML <textarea> 대신 Lynx native <textarea> element를 렌더링합니다.
readOnly 상태에서는 native focus·selection·잘라내기 메뉴를 제거하기 위해 <text> element로 렌더링합니다. 이 상태의 ref는 <text>를 가리키며 textarea 전용 UI method와 이벤트는 사용할 수 없습니다.
onChange 대신 snippet TextField의 onValueChange를 사용합니다. 원문과 grapheme 단위로 자른 값을 함께 제공합니다.
native bindinput은 TextFieldTextarea에 추가로 전달할 수 있습니다.
Field.Label과 입력의 DOM id 연결이 없으므로 accessibility-label을 입력에 직접 제공합니다.
autoresize는 DOM scrollHeight 대신 native intrinsic height를 사용합니다. iOS는 wrapper가 세로 여백을 소유하고, Android는 EditText 자체가 세로 여백과 최소 높이를 소유해 native drawing 경계에서 첫 줄이 잘리지 않도록 합니다.
Android에서는 CSS line-height가 native textarea에 적용되지 않아 line-spacing="3.2px"를 기본 적용합니다. 명시적인 line-spacing 값이 이 기본값보다 우선합니다.
controlled textarea도 native 입력 이벤트를 그대로 유지하고, 외부에서 값이 달라진 경우에만 setValue로 동기화합니다. 입력마다 readonly를 토글하지 않아 줄 추가 시 native scroll offset과 높이 측정이 초기화되지 않습니다.
Android의 fullscreen extract input은 기본적으로 비활성화합니다. 필요한 경우 android-fullscreen-mode={true}를 명시합니다.
KeyboardAvoidingScrollView가 키보드 회피를 전담하는 화면에서는 Android host window의 별도 pan/resize를 막기 위해 android-set-soft-input-mode="nothing"을 명시할 수 있습니다. 이 값은 host window 전역에 영향을 주므로 컴포넌트가 자동으로 적용하지 않습니다.
size="responsive"는 CSS viewport breakpoint가 없는 Lynx에서 지원하지 않습니다. large 또는 medium을 명시합니다.

Unsupported Lynx Features

HTML form submit, browser validation, aria-describedby id 연결은 지원하지 않습니다.
큰 textarea에서 현재 caret 위치만 기준으로 키보드를 회피하는 기능은 지원하지 않습니다. 현재는 Field·TextField·native 입력 영역 중 안전 영역에 맞는 가장 큰 영역을 선택합니다.

Text Field Textarea

Installation

의존성 설치

아래 코드를 복사 후 붙여넣고 사용하세요

Props

`TextField`

`TextFieldTextarea`

Usage

Controlled value

Autoresizing

Grapheme limit

Keyboard avoidance

Web Version Differences

Unsupported Lynx Features

목차

Text Field Textarea

Manual Installation

의존성 설치

아래 코드를 복사 후 붙여넣고 사용하세요

목차