TextInput

TextInput

사용자로부터 문자열 입력을 받는 컴포넌트예요. Input과 Input.Wrapper 컴포넌트의 기능과 모든 input 요소 props를 지원해요.

출처: 문서

본문

사용법 (Usage)

TextInput 컴포넌트는 Input과 Input.Wrapper 컴포넌트의 기능과 모든 input 요소 props를 지원해요. TextInput 문서에는 컴포넌트가 지원하는 모든 기능이 포함되어 있지 않아요. 사용 가능한 모든 기능은 Input 문서에서 확인할 수 있어요.

import { TextInput } from '@mantine/core';

function Demo() {
  return (
    <TextInput
      label="Input label"
      description="Input description"
      placeholder="Enter your name"
    />
  );
}

로딩 상태 (Loading state)

loading prop을 설정하면 로딩 인디케이터를 표시해요. 기본적으로 로더는 입력 오른쪽에 표시돼요. loadingPosition prop을 'left' 또는 'right'로 설정해 위치를 바꿀 수 있어요. 이는 API 호출, 검색, 검증 같은 비동기 작업에 유용해요.

import { TextInput } from '@mantine/core';

function Demo() {
  return <TextInput loading loadingPosition="right" />;
}

제어 컴포넌트 (Controlled)

import { useState } from 'react';
import { TextInput } from '@mantine/core';

function Demo() {
  const [value, setValue] = useState('');
  return (
    <TextInput
      value={value}
      onChange={(event) => setValue(event.currentTarget.value)}
    />
  );
}

비제어 컴포넌트 (Uncontrolled)

TextInput는 네이티브 input[type="text"]와 같은 방식으로 비제어 폼과 함께 사용할 수 있어요. 폼 제출 시 FormData 객체에 텍스트 입력 값을 포함하려면 name 속성을 설정해요. 비제어 폼에서 초기 값을 제어하려면 defaultValue prop을 사용해요.

import { TextInput } from '@mantine/core';

function Demo() {
  return (
    <form
      onSubmit={(event) => {
        event.preventDefault();
        const formData = new FormData(event.currentTarget);
        console.log('Text input value:', formData.get('name'));
      }}
    >
      <TextInput name="name" placeholder="Your name" />
      <button type="submit">Submit</button>
    </form>
  );
}

왼쪽·오른쪽 섹션 (Left and right sections)

TextInput는 leftSection과 rightSection props를 지원해요. 이 섹션들은 입력 래퍼 안에 절대 위치(absolute positioning)로 렌더링돼요. 아이콘, 입력 컨트롤, 기타 요소를 표시하는 데 사용할 수 있어요.

섹션 스타일과 콘텐츠를 제어하는 props:

• rightSection / leftSection – 입력의 해당 측면에 렌더링할 React 노드
• rightSectionWidth / leftSectionWidth – 오른쪽 섹션의 너비와 입력 해당 측면의 패딩을 제어해요. 기본적으로 컴포넌트 size prop으로 제어돼요.
• rightSectionPointerEvents / leftSectionPointerEvents – 섹션의 pointer-events 속성을 제어해요. 비상호작용 요소를 렌더링하려면 none으로 설정해 클릭이 입력으로 전달되게 해요.

import { TextInput } from '@mantine/core';
import { AtIcon } from '@phosphor-icons/react';

function Demo() {
  const icon = <AtIcon size={16} />;
  return (
    <>
      <TextInput leftSection={icon} label="Your email" placeholder="Your email" />
      <TextInput rightSection={icon} label="Your email" placeholder="Your email" />
    </>
  );
}

오류 상태 (Error state)

불리언 오류 또는 오류 메시지와 함께 TextInput를 표시할 수 있어요.

import { TextInput } from '@mantine/core';

function Demo() {
  return (
    <>
      <TextInput label="Boolean error" error />
      <TextInput label="With error message" error="Invalid name" />
    </>
  );
}

성공 상태 (Success state)

import { TextInput } from '@mantine/core';

function Demo() {
  return <TextInput label="Text Input" description="Looks good!" />;
}

비활성 상태 (Disabled state)

import { TextInput } from '@mantine/core';

function Demo() {
  return <TextInput disabled />;
}

Styles API

TextInput는 Styles API를 지원해요. classNames prop으로 컴포넌트의 내부 요소에 스타일을 추가할 수 있어요. 자세한 내용은 Styles API 문서를 참고해요.

요소 ref 가져오기 (Get element ref)

import { useRef } from 'react';
import { TextInput } from '@mantine/core';

function Demo() {
  const ref = useRef<HTMLInputElement>(null);
  return <TextInput ref={ref} />;
}

접근성 (Accessibility)

TextInput를 label prop 없이 사용하면 화면 판독기가 제대로 알려주지 못해요. aria-label을 설정하면 라벨이 보이지 않아도 화면 판독기가 알려줘요. label prop을 설정하면 별도로 aria-label을 지정할 필요 없이 접근성이 확보돼요.

import { TextInput } from '@mantine/core';

// 처리되지 않는 입력 – 화면 판독기가 제대로 알려주지 않아요
// function Demo() { return <TextInput />; }

// 접근 가능 입력 – aria-label이 있어요
function Demo() {
  return <TextInput aria-label="Your name" />;
}

더 알아보기 (Learn more)

• Textarea
• Autocomplete
• Input