입력
입력 (Input)
텍스트를 입력받는 기본 입력 상자 컴포넌트예요. 검색, 비밀번호, 텍스트 영역, OTP 등 다양한 형태로 쓸 수 있어요.
출처: 문서
본문
언제 사용하나요 (When To Use)
- 폼 필드에서 사용자 입력이 필요할 때 사용해요.
- 검색 입력이 필요할 때 사용해요.
예시 (Examples)
기본 사용법 (Basic usage)
기본 사용법 예시예요.
import React from 'react';
import { Input } from 'antd';
const App: React.FC = () => <Input placeholder="Basic usage" />;
export default App;
세 가지 크기의 Input (Three sizes of Input)
Input 상자에는 large(40px), medium(32px), small(24px) 세 가지 크기가 있어요.
import React from 'react';
import { UserOutlined } from '@ant-design/icons';
import { Flex, Input } from 'antd';
const App: React.FC = () => (
<Flex vertical gap="medium">
<Input size="large" placeholder="large size" prefix={<UserOutlined />} />
<Input placeholder="default size" prefix={<UserOutlined />} />
<Input size="small" placeholder="small size" prefix={<UserOutlined />} />
</Flex>
);
export default App;
변형 (Variants)
Input의 변형에는 네 가지가 있어요. outlined, filled, borderless, underlined.
import React from 'react';
import { Flex, Input } from 'antd';
const App: React.FC = () => (
<Flex vertical gap={12}>
<Input placeholder="Outlined" />
<Input placeholder="Filled" variant="filled" />
<Input placeholder="Borderless" variant="borderless" />
<Input placeholder="Underlined" variant="underlined" />
<Input.Search placeholder="Filled" variant="filled" />
</Flex>
);
export default App;
컴팩트 스타일 (Compact Style)
Space.Compact로 컴팩트 스타일을 만들어요. 자세한 내용은 Space.Compact 문서를 참고해요.
import React from 'react';
import { SearchOutlined } from '@ant-design/icons';
import { Button, Input, Select, Space } from 'antd';
const { Search } = Input;
const options = [
{
value: 'zhejiang',
label: 'Zhejiang',
},
{
value: 'jiangsu',
label: 'Jiangsu',
},
];
const App: React.FC = () => (
<Space vertical size="medium">
<Space.Compact>
<Input defaultValue="26888888" />
</Space.Compact>
<Space.Compact>
<Input style={{ width: '20%' }} defaultValue="0571" />
<Input style={{ width: '80%' }} defaultValue="26888888" />
</Space.Compact>
<Space.Compact>
<Space.Addon>https://</Space.Addon>
<Search placeholder="input search text" allowClear />
</Space.Compact>
<Space.Compact style={{ width: '100%' }}>
<Input defaultValue="Combine input and button" />
<Button type="primary">Submit</Button>
</Space.Compact>
<Space.Compact>
<Select defaultValue="Zhejiang" options={options} />
<Input defaultValue="Xihu District, Hangzhou" />
</Space.Compact>
<Space.Compact size="large">
<Space.Addon>
<SearchOutlined />
</Space.Addon>
<Input placeholder="large size" />
<Input placeholder="another input" />
</Space.Compact>
</Space>
);
export default App;
검색 상자 (Search box)
표준 입력과 검색 버튼을 묶어 검색 상자를 만드는 예시예요.
import React from 'react';
import { AudioOutlined } from '@ant-design/icons';
import { Input, Space } from 'antd';
import type { GetProps } from 'antd';
type SearchProps = GetProps<typeof Input.Search>;
const { Search } = Input;
const suffix = <AudioOutlined style={{ fontSize: 16, color: '#1677ff' }} />;
const onSearch: SearchProps['onSearch'] = (value, _e, info) => console.log(info?.source, value);
const App: React.FC = () => (
<Space vertical>
<Search placeholder="input search text" onSearch={onSearch} style={{ width: 200 }} />
<Search placeholder="input search text" allowClear onSearch={onSearch} style={{ width: 200 }} />
<Space.Compact>
<Space.Addon>https://</Space.Addon>
<Search placeholder="input search text" allowClear onSearch={onSearch} />
</Space.Compact>
<Search placeholder="input search text" onSearch={onSearch} enterButton />
<Search
placeholder="input search text"
allowClear
enterButton="Search"
size="large"
onSearch={onSearch}
/>
<Search
placeholder="input search text"
enterButton="Search"
size="large"
suffix={suffix}
onSearch={onSearch}
/>
</Space>
);
export default App;
로딩이 있는 검색 상자 (Search box with loading)
onSearch 시 검색 로딩 상태예요.
import React from 'react';
import { Input } from 'antd';
const { Search } = Input;
const App: React.FC = () => (
<>
<Search placeholder="input search loading default" loading />
<br />
<br />
<Search placeholder="input search loading with enterButton" loading enterButton />
<br />
<br />
<Search placeholder="input search text" enterButton="Search" size="large" loading />
</>
);
export default App;
TextArea
여러 줄 입력용이에요.
import React from 'react';
import { Input } from 'antd';
const { TextArea } = Input;
const App: React.FC = () => (
<>
<TextArea rows={4} />
<br />
<br />
<TextArea rows={4} placeholder="maxLength is 6" maxLength={6} />
</>
);
export default App;
콘텐츠에 맞춰 높이 자동 조정 (Autosizing the height to fit the content)
Input의 textarea 타입에 대한 autoSize prop은 콘텐츠에 따라 높이를 자동으로 조정해요. autoSize에 옵션 객체를 제공하면 textarea가 자동으로 조정할 최소·최대 줄 수를 지정할 수 있어요.
import React, { useState } from 'react';
import { Input } from 'antd';
const { TextArea } = Input;
const App: React.FC = () => {
const [value, setValue] = useState('');
return (
<>
<TextArea placeholder="Autosize height based on content lines" autoSize />
<div style={{ margin: '24px 0' }} />
<TextArea
placeholder="Autosize height with minimum and maximum number of lines"
autoSize={{ minRows: 2, maxRows: 6 }}
/>
<div style={{ margin: '24px 0' }} />
<TextArea
value={value}
onChange={(e) => setValue(e.target.value)}
placeholder="Controlled autosize"
autoSize={{ minRows: 3, maxRows: 5 }}
/>
</>
);
};
export default App;
OTP
일회용 비밀번호(one-time password) 입력이에요.
import React from 'react';
import { Flex, Input, Typography } from 'antd';
import type { GetProps } from 'antd';
type OTPProps = GetProps<typeof Input.OTP>;
const { Title } = Typography;
const App: React.FC = () => {
const onChange: OTPProps['onChange'] = (text) => {
console.log('onChange:', text);
};
const onInput: OTPProps['onInput'] = (value) => {
console.log('onInput:', value);
};
const sharedProps: OTPProps = {
onChange,
onInput,
};
return (
<Flex gap="medium" align="flex-start" vertical>
<Title level={5}>With formatter (Upcase)</Title>
<Input.OTP formatter={(str) => str.toUpperCase()} {...sharedProps} />
<Title level={5}>With Disabled</Title>
<Input.OTP disabled {...sharedProps} />
<Title level={5}>With Length (8)</Title>
<Input.OTP length={8} {...sharedProps} />
<Title level={5}>With variant</Title>
<Input.OTP variant="filled" {...sharedProps} />
<Title level={5}>With custom display character</Title>
<Input.OTP mask="🔒" {...sharedProps} />
<Title level={5}>With custom ReactNode separator</Title>
<Input.OTP separator={<span>/</span>} {...sharedProps} />
<Title level={5}>With custom function separator</Title>
<Input.OTP
separator={(i) => <span style={{ color: i & 1 ? 'red' : 'blue' }}>—</span>}
{...sharedProps}
/>
</Flex>
);
};
export default App;
포맷 툴팁 입력 (Format Tooltip Input)
Input을 Tooltip 컴포넌트와 함께 사용해 숫자 입력을 만들 수 있어요. 아주 긴 콘텐츠 표시에 좋은 경험을 제공해요.
import React, { useState } from 'react';
import { Input, Tooltip } from 'antd';
import { createStyles } from 'antd-style';
const useStyles = createStyles((props) => {
const { css, prefixCls, cssVar } = props;
return {
numericInput: css`
.${prefixCls}-tooltip-container {
min-width: 32px;
min-height: 38px;
}
`,
numericInputTitle: css`
font-size: ${cssVar.fontSize};
`,
};
});
interface NumericInputProps {
style: React.CSSProperties;
value: string;
onChange: (value: string) => void;
}
const formatNumber = (value: number) => new Intl.NumberFormat().format(value);
const NumericInput: React.FC<NumericInputProps> = (props) => {
const { value, onChange } = props;
const { styles } = useStyles();
const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
const { value: inputValue } = e.target;
const reg = /^-?\d*(\.\d*)?$/;
if (reg.test(inputValue) || inputValue === '' || inputValue === '-') {
onChange(inputValue);
}
};
// '.' at the end or only '-' in the input box.
const handleBlur: React.FocusEventHandler<HTMLInputElement> = () => {
let valueTemp = value;
if (value.charAt(value.length - 1) === '.' || value === '-') {
valueTemp = value.slice(0, -1);
}
onChange(valueTemp.replace(/0*(\d+)/, '$1'));
};
const title = value ? (
<span className={styles.numericInputTitle}>
{value !== '-' ? formatNumber(Number(value)) : '-'}
</span>
) : (
'Input a number'
);
return (
<Tooltip
destroyOnHidden
trigger={['focus']}
title={title}
placement="topLeft"
classNames={{ root: styles.numericInput }}
>
<Input
{...props}
onChange={handleChange}
onBlur={handleBlur}
placeholder="Input a number"
maxLength={16}
/>
</Tooltip>
);
};
const App: React.FC = () => {
const [value, setValue] = useState('');
return <NumericInput style={{ width: 120 }} value={value} onChange={setValue} />;
};
export default App;
prefix와 suffix
입력 안쪽에 접두사나 접미사 아이콘을 추가해요. 참고: Input.Password의 suffix prop은 버전 5.27.0부터 지원돼요.
import React from 'react';
import { InfoCircleOutlined, LockOutlined, UserOutlined } from '@ant-design/icons';
import { Input, Tooltip } from 'antd';
const App: React.FC = () => (
<>
<Input
placeholder="Enter your username"
prefix={<UserOutlined style={{ color: 'rgba(0,0,0,.25)' }} />}
suffix={
<Tooltip title="Extra information">
<InfoCircleOutlined style={{ color: 'rgba(0,0,0,.45)' }} />
</Tooltip>
}
/>
<br />
<br />
<Input prefix="￥" suffix="RMB" />
<br />
<br />
<Input prefix="￥" suffix="RMB" disabled />
<br />
<br />
<Input.Password
suffix={<LockOutlined />} // `suffix` available since `5.27.0`
placeholder="input password support suffix"
/>
</>
);
export default App;
비밀번호 상자 (Password box)
비밀번호 타입의 Input이에요.
import React from 'react';
import { EyeInvisibleOutlined, EyeTwoTone } from '@ant-design/icons';
import { Button, Input, Space } from 'antd';
const App: React.FC = () => {
const [passwordVisible, setPasswordVisible] = React.useState(false);
return (
<Space vertical>
<Input.Password placeholder="input password" />
<Input.Password
placeholder="input password"
iconRender={(visible) => (visible ? <EyeTwoTone /> : <EyeInvisibleOutlined />)}
/>
<Space>
<Input.Password
placeholder="input password"
visibilityToggle={{ visible: passwordVisible, onVisibleChange: setPasswordVisible }}
/>
<Button style={{ width: 80 }} onClick={() => setPasswordVisible((prevState) => !prevState)}>
{passwordVisible ? 'Hide' : 'Show'}
</Button>
</Space>
<Input.Password disabled placeholder="disabled input password" />
</Space>
);
};
export default App;
지우기 아이콘 (With clear icon)
제거 아이콘이 있는 입력 상자예요. 아이콘을 클릭하면 모든 내용을 삭제해요.
import React from 'react';
import { Input } from 'antd';
const { TextArea } = Input;
const onChange = (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => {
console.log(e);
};
const App: React.FC = () => (
<>
<Input placeholder="input with clear icon" allowClear onChange={onChange} />
<br />
<br />
<TextArea placeholder="textarea with clear icon" allowClear onChange={onChange} />
</>
);
export default App;
문자 수 세기 (With character counting)
문자 수를 보여 줘요.
import React from 'react';
import { Flex, Input } from 'antd';
const { TextArea } = Input;
const onChange = (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) => {
console.log('Change:', e.target.value);
};
const App: React.FC = () => (
<Flex vertical gap={32}>
<Input showCount maxLength={20} onChange={onChange} />
<TextArea showCount maxLength={100} onChange={onChange} placeholder="can resize" />
<TextArea
showCount
maxLength={100}
onChange={onChange}
placeholder="disable resize"
style={{ height: 120, resize: 'none' }}
/>
</Flex>
);
export default App;
커스텀 카운트 로직 (Custom count logic)
어떤 시나리오에서는 카운팅 기능을 커스터마이즈해야 해요. (예: 이모지 길이를 1로 계산.) count 속성으로 구현할 수 있어요. count.max 속성은 네이티브 maxLength의 한계를 넘어서요.
import React from 'react';
import { Flex, Input, Typography } from 'antd';
import { runes } from 'runes2';
const App: React.FC = () => (
<Flex vertical gap={16}>
<div>
<Typography.Title level={5}>Exceed Max</Typography.Title>
<Input
count={{
show: true,
max: 10,
}}
defaultValue="Hello, antd!"
/>
</div>
<div>
<Typography.Title level={5}>Emoji count as length 1</Typography.Title>
<Input
count={{
show: true,
strategy: (txt) => runes(txt).length,
}}
defaultValue="🔥🔥🔥"
/>
</div>
<div>
<Typography.Title level={5}>Not exceed max</Typography.Title>
<Input
count={{
show: true,
max: 6,
strategy: (txt) => runes(txt).length,
exceedFormatter: (txt, { max }) => runes(txt).slice(0, max).join(''),
}}
defaultValue="🔥 antd"
/>
</div>
</Flex>
);
export default App;
상태 (Status)
status로 Input에 상태를 추가해요. error 또는 warning이 될 수 있어요.
import React from 'react';
import ClockCircleOutlined from '@ant-design/icons/ClockCircleOutlined';
import { Input, Space } from 'antd';
const App: React.FC = () => (
<Space vertical style={{ width: '100%' }}>
<Input status="error" placeholder="Error" />
<Input status="warning" placeholder="Warning" />
<Input status="error" prefix={<ClockCircleOutlined />} placeholder="Error with prefix" />
<Input status="warning" prefix={<ClockCircleOutlined />} placeholder="Warning with prefix" />
</Space>
);
export default App;
포커스 (Focus)
추가 옵션과 함께 포커스를 맞춰요.
import React, { useRef, useState } from 'react';
import type { InputRef } from 'antd';
import { Button, Input, Space, Switch } from 'antd';
const App: React.FC = () => {
const inputRef = useRef<InputRef>(null);
const [input, setInput] = useState(true);
const sharedProps = {
style: { width: '100%' },
defaultValue: 'Ant Design love you!',
ref: inputRef,
};
return (
<Space vertical style={{ width: '100%' }}>
<Space wrap>
<Button
onClick={() => {
inputRef.current?.focus({ cursor: 'start' });
}}
>
Focus at first
</Button>
<Button
onClick={() => {
inputRef.current?.focus({ cursor: 'end' });
}}
>
Focus at last
</Button>
<Button
onClick={() => {
inputRef.current?.focus({ cursor: 'all' });
}}
>
Focus to select all
</Button>
<Button
onClick={() => {
inputRef.current?.focus({ preventScroll: true });
}}
>
Focus prevent scroll
</Button>
<Switch
checked={input}
checkedChildren="Input"
unCheckedChildren="TextArea"
onChange={() => {
setInput((prev) => !prev);
}}
/>
</Space>
<br />
{input ? <Input {...sharedProps} /> : <Input.TextArea {...sharedProps} />}
</Space>
);
};
export default App;
시맨틱 DOM 스타일링 (Custom semantic dom styling)
classNames와 styles로 객체나 함수를 전달해 Input의 시맨틱 DOM 스타일을 커스터마이즈할 수 있어요.
import React from 'react';
import { Flex, Input } from 'antd';
import type { GetProp, GetProps } from 'antd';
import { createStaticStyles } from 'antd-style';
const styles = createStaticStyles(({ css, cssVar }) => ({
root: css`
border-width: ${cssVar.lineWidth};
border-radius: ${cssVar.borderRadius};
transition: box-shadow ${cssVar.motionDurationMid};
&:hover {
border: 1px solid #d9d9d9;
}
&:focus-visible {
border-color: lab(66.128% 0 0);
box-shadow: 0 0 0 4px color-mix(in oklab, lab(66.128% 0 0) 50%, transparent);
}
`,
}));
type InputProps = GetProps<typeof Input>;
type PasswordProps = GetProps<typeof Input.Password>;
type TextAreaProps = GetProps<typeof Input.TextArea>;
type OTPProps = GetProps<typeof Input.OTP>;
type SearchProps = GetProps<typeof Input.Search>;
const { Search, TextArea, OTP, Password } = Input;
const stylesFn: InputProps['styles'] = (info) => {
if (info.props.size === 'medium') {
return {
root: {
borderColor: '#696FC7',
},
};
}
return {};
};
const stylesFnTextArea: TextAreaProps['styles'] = (
info,
): GetProp<TextAreaProps, 'styles', 'Return'> => {
if (info.props.showCount) {
return {
root: { borderColor: '#BDE3C3' },
textarea: { resize: 'none' },
count: { color: '#BDE3C3' },
};
}
return {};
};
const stylesFnPassword: PasswordProps['styles'] = (
info,
): GetProp<PasswordProps, 'styles', 'Return'> => {
if (info.props.size === 'medium') {
return {
root: {
borderColor: '#F5D3C4',
},
};
}
return {};
};
const stylesFnOTP: OTPProps['styles'] = (info): GetProp<OTPProps, 'styles', 'Return'> => {
if (info.props.size === 'medium') {
return {
root: {
borderWidth: 0,
},
input: {
borderColor: '#6E8CFB',
width: 32,
},
};
}
return {};
};
const stylesFnSearch: SearchProps['styles'] = (info): GetProp<SearchProps, 'styles', 'Return'> => {
if (info.props.size === 'large') {
return {
root: { color: '#4DA8DA', borderWidth: 0 },
input: { color: '#4DA8DA', borderColor: '#4DA8DA' },
prefix: { color: '#4DA8DA' },
suffix: { color: '#4DA8DA' },
count: { color: '#4DA8DA' },
button: {
root: { color: '#4DA8DA', borderColor: '#4DA8DA' },
icon: { color: '#4DA8DA' },
},
};
}
return {};
};
const App: React.FC = () => {
const classNames = styles;
return (
<Flex vertical gap="large">
<Input classNames={classNames} placeholder="Object" name="input-object" />
<Input
classNames={classNames}
styles={stylesFn}
placeholder="Function"
size="medium"
name="input-fn"
/>
<TextArea
classNames={classNames}
styles={stylesFnTextArea}
value="TextArea"
showCount
name="textarea-fn"
/>
<Password
classNames={classNames}
styles={stylesFnPassword}
value="Password"
size="medium"
name="password-fn"
/>
<OTP classNames={classNames} styles={stylesFnOTP} size="medium" length={6} separator="*" />
<Search
classNames={classNames}
styles={stylesFnSearch}
size="large"
placeholder="Search"
name="search-fn"
/>
</Flex>
);
};
export default App;
API
공통 props는 Common props를 참고해요.
Input
| 속성 (Property) | 설명 (Description) | 타입 (Type) | 기본값 (Default) | 버전 (Version) | 글로벌 설정 |
|---|---|---|---|---|---|
| 입력 필드 뒤(오른쪽)에 표시되는 라벨 텍스트예요. Space.Compact를 대신 사용해 주세요. | ReactNode | - | × | ||
| 입력 필드 앞(왼쪽)에 표시되는 라벨 텍스트예요. Space.Compact를 대신 사용해 주세요. | ReactNode | - | × | ||
| allowClear | 입력 내용을 지우는 지우기 아이콘을 표시할지 여부 | boolean | { clearIcon: ReactNode, disabled?: boolean } | - | disabled: 6.4.0 | 5.15.0 |
테두리 스타일 여부예요. variant를 대신 사용해 주세요. |
boolean | true | 4.5.0 | × | |
| classNames | 컴포넌트 내부의 각 시맨틱 구조에 대한 class를 지정해요. 객체 또는 함수를 지원해요. | Record<SemanticDOM, string> | (info: { props })=> Record<SemanticDOM, string> | - | 5.4.0 | 5.7.0 |
| count | 문자 수 세기 설정 | CountConfig | - | 5.10.0 | × |
| defaultValue | 초기 입력 콘텐츠 | string | - | × | |
| disabled | 입력 비활성화 여부 | boolean | false | - | × |
| id | 입력을 위한 ID | string | - | × | |
| maxLength | Input의 최대 문자 수 | number | - | × | |
| prefix | Input의 접두사 아이콘 | ReactNode | - | × | |
| showCount | 문자 수를 표시할지 여부 | boolean | { formatter: (info: { value: string, count: number, maxLength?: number }) => ReactNode } | false | 4.18.0 info.value: 4.23.0 | × |
| status | 검증 상태 설정 | 'error' | 'warning' | - | 4.19.0 | × |
| styles | 컴포넌트 내부의 각 시맨틱 구조에 대한 인라인 스타일을 지정해요. 객체 또는 함수를 지원해요. | Record<SemanticDOM, CSSProperties> | (info: { props })=> Record<SemanticDOM, CSSProperties> | - | 5.4.0 | 5.7.0 |
| size | 입력 상자의 크기. 참고: 폼 컨텍스트에서는 medium 크기가 사용돼요. |
large | medium | small |
- | × | |
| suffix | Input의 접미사 아이콘 | ReactNode | - | × | |
| type | 입력 타입이에요. MDN 참고. (type="textarea" 대신 Input.TextArea 사용.) |
string | text |
× | |
| value | 입력 콘텐츠 값 | string | - | × | |
| variant | Input의 변형 | outlined | borderless | filled | underlined |
outlined |
5.13.0 | underlined: 5.24.0 |
5.19.0 |
| onChange | 사용자 입력 시 콜백 | function(e) | - | × | |
| onPressEnter | Enter 키를 누를 때 트리거되는 콜백 함수 | function(e) | - | × | |
| onClear | 지우기 버튼을 클릭할 때 콜백 | () => void | - | 5.20.0 | × |
Input을Form.Item컨텍스트에서 사용할 때Form.Item에idprops가 정의되어 있으면Input의value,defaultValue,idprops가 자동으로 설정돼요.
Input의 나머지 props는 원래 input과 정확히 같아요.
CountConfig
interface CountConfig {
// Max character count. Different from the native `maxLength`, it will be marked warning but not truncated
max?: number;
// Custom character count, for example, the standard emoji length is greater than 1, you can customize the counting strategy to change it to 1
strategy?: (value: string) => number;
// Same as `showCount`
show?: boolean | ((args: { value: string; count: number; maxLength?: number }) => ReactNode);
// Custom clipping logic when the number of characters exceeds `count.max`, no clipping when not configured
exceedFormatter?: (value: string, config: { max: number }) => string;
}
Input.TextArea
Input과 같고 추가로:
| 속성 (Property) | 설명 (Description) | 타입 (Type) | 기본값 (Default) | 버전 (Version) | 글로벌 설정 |
|---|---|---|---|---|---|
| autoSize | 높이 자동 크기 기능. true | false 또는 객체 { minRows: 2, maxRows: 6 }로 설정할 수 있어요. |
boolean | object | false | × | |
| classNames | 컴포넌트 내부의 각 시맨틱 구조에 대한 class를 지정해요. 객체 또는 함수를 지원해요. | Record<SemanticDOM, string> | (info: { props }) => Record<SemanticDOM, string> | - | 5.4.0 | 5.15.0 |
| styles | 컴포넌트 내부의 각 시맨틱 구조에 대한 인라인 스타일을 지정해요. 객체 또는 함수를 지원해요. | Record<SemanticDOM, CSSProperties> | (info: { props }) => Record<SemanticDOM, CSSProperties> | - | 5.4.0 | 5.15.0 |
Input.TextArea의 나머지 props는 원래 textarea와 같아요.
Input.Search
| 속성 (Property) | 설명 (Description) | 타입 (Type) | 기본값 (Default) | 버전 (Version) | 글로벌 설정 |
|---|---|---|---|---|---|
| classNames | 컴포넌트 내부의 각 시맨틱 구조에 대한 class를 지정해요. 객체 또는 함수를 지원해요. | Record<SemanticDOM, string> | (info: { props }) => Record<SemanticDOM, string> | - | 6.0.0 | 6.0.0 |
| enterButton | false는 기본 버튼 색, true는 primary 색을 사용하며, 커스텀 버튼을 제공할 수도 있어요. addonAfter와 충돌해요. | ReactNode | false | × | |
| loading | 로딩이 있는 검색 상자 | boolean | false | × | |
| onSearch | 검색 아이콘, 지우기 아이콘을 클릭하거나 Enter 키를 누를 때 트리거되는 콜백 함수 | function(value, event, { source: "input" | "clear" }) | - | × | |
| styles | 컴포넌트 내부의 각 시맨틱 구조에 대한 인라인 스타일을 지정해요. 객체 또는 함수를 지원해요. | Record<SemanticDOM, CSSProperties> | (info: { props }) => Record<SemanticDOM, CSSProperties> | - | 6.0.0 | 6.0.0 |
| searchIcon | 검색 아이콘 커스터마이즈 | ReactNode | - | 6.4.0 | 6.4.0 |
| variant | Input의 변형 | outlined | borderless | filled | underlined |
outlined |
5.13.0 | underlined: 5.24.0 |
6.6.0 |
Input의 모든 props를 지원해요.
Input.Password
| 속성 (Property) | 설명 (Description) | 타입 (Type) | 기본값 (Default) | 버전 (Version) | 글로벌 설정 |
|---|---|---|---|---|---|
| classNames | 시맨틱 DOM class | Record<SemanticDOM, string> | - | 5.4.0 | 6.4.0 |
| iconRender | 커스텀 토글 버튼 | (visible) => ReactNode | (visible) => (visible ? <EyeOutlined /> : <EyeInvisibleOutlined />) | 4.3.0 | 6.4.0 |
| styles | 시맨틱 DOM 스타일 | Record<SemanticDOM, CSSProperties> | - | 5.4.0 | 6.4.0 |
| variant | Input의 변형 | outlined | borderless | filled | underlined |
outlined |
5.13.0 | underlined: 5.24.0 |
6.6.0 |
| visibilityToggle | 토글 버튼 표시 여부 또는 비밀번호 표시 제어 | boolean | VisibilityToggle | true | × |
Input.OTP
5.16.0에 추가됐어요.
개발자 참고
maskprop이 문자열일 때는 단일 문자나 단일 이모지를 받는 것을 권장해요. 여러 문자나 여러 이모지를 전달하면 경고가 발생해요.
| 속성 (Property) | 설명 (Description) | 타입 (Type) | 기본값 (Default) | 버전 (Version) | 글로벌 설정 |
|---|---|---|---|---|---|
| autoComplete | input 요소의 autocomplete 속성이에요. OTP 자동 채움용 one-time-code 등. |
string | - | 6.3.0 | × |
| classNames | 컴포넌트 내부의 각 시맨틱 구조에 대한 class를 지정해요. 객체 또는 함수를 지원해요. | Record<SemanticDOM, string> | (info: { props }) => Record<SemanticDOM, string> | - | 6.0.0 | 6.0.0 |
| defaultValue | 기본값 | string | - | × | |
| disabled | 입력 비활성화 여부 | boolean | false | × | |
| formatter | 표시 포맷이에요. 빈 필드는 로 채워져요. |
(value: string) => string | - | × | |
| separator | 지정한 인덱스의 입력 상자 뒤에 구분자를 렌더링해요. | ReactNode |((i: number) => ReactNode) | - | 5.24.0 | × |
| styles | 컴포넌트 내부의 각 시맨틱 구조에 대한 인라인 스타일을 지정해요. 객체 또는 함수를 지원해요. | Record<SemanticDOM, CSSProperties> | (info: { props }) => Record<SemanticDOM, CSSProperties> | - | 6.0.0 | 6.0.0 |
| mask | 커스텀 표시예요. 원래 값은 수정되지 않아요. | boolean | string | false |
5.17.0 |
× |
| length | 입력 요소의 수 | number | 6 | × | |
| status | 검증 상태 설정 | 'error' | 'warning' | - | × | |
| size | 입력 상자의 크기 | small | medium | large |
medium |
× | |
| variant | Input의 변형 | outlined | borderless | filled | underlined |
outlined |
underlined: 5.24.0 |
6.6.0 |
| value | 입력 콘텐츠 값 | string | - | × | |
| onChange | 모든 필드가 채워졌을 때 트리거돼요. | (value: string) => void | - | × | |
| onInput | 입력 값이 변경될 때 트리거돼요. | (value: string[]) => void | - | 5.22.0 |
× |
VisibilityToggle
| 속성 (Property) | 설명 (Description) | 타입 (Type) | 기본값 (Default) | 버전 (Version) |
|---|---|---|---|---|
| tabIndex | 토글 버튼의 tabIndex 설정 |
number | 0 | 6.5.0 |
| visible | 비밀번호를 보여 줄지 숨길지 여부 | boolean | false | 4.24.0 |
| onVisibleChange | 비밀번호 표시 여부가 변경될 때 실행되는 콜백 | (visible) => void | - | 4.24.0 |
Input 메서드 (Input Methods)
| 이름 (Name) | 설명 (Description) | 매개변수 (Parameters) | 버전 (Version) |
|---|---|---|---|
| blur | 포커스 제거 | - | |
| focus | 포커스 획득 | (option?: { preventScroll?: boolean, cursor?: 'start' | 'end' | 'all' }) | option - 4.10.0 |
시맨틱 DOM (Semantic DOM)
Input {#semantic-input}
시맨틱 DOM 구조는 https://ant.design/components/input/semantic_input.md 에서 확인할 수 있어요.
Input.TextArea {#semantic-textarea}
시맨틱 DOM 구조는 https://ant.design/components/input/semantic_textarea.md 에서 확인할 수 있어요.
Input.Search {#semantic-search}
시맨틱 DOM 구조는 https://ant.design/components/input/semantic_search.md 에서 확인할 수 있어요.
Input.Password {#semantic-password}
시맨틱 DOM 구조는 https://ant.design/components/input/semantic_password.md 에서 확인할 수 있어요.
Input.OTP {#semantic-otp}
시맨틱 DOM 구조는 https://ant.design/components/input/semantic_otp.md 에서 확인할 수 있어요.
디자인 토큰 (Design Token)
컴포넌트 토큰 (Input) (Component Token)
| 토큰 이름 (Token Name) | 설명 (Description) | 타입 (Type) | 기본값 (Default Value) |
|---|---|---|---|
| activeBg | 입력 상자가 활성화될 때 배경색 | string | #ffffff |
| activeBorderColor | 활성 테두리 색 | string | #1677ff |
| activeShadow | 활성 시 box-shadow | string | 0 0 0 2px rgba(5,145,255,0.1) |
| addonBg | addon의 배경색 | string | rgba(0,0,0,0.02) |
| errorActiveShadow | 오류 상태에서 활성 시 box-shadow | string | 0 0 0 2px rgba(255,38,5,0.06) |
| hoverBg | 입력 상자를 hover할 때 배경색 | string | #ffffff |
| hoverBorderColor | hover 테두리 색 | string | #4096ff |
| inputFontSize | 글자 크기 | number | 14 |
| inputFontSizeLG | 큰 글자 크기 | number | 16 |
| inputFontSizeSM | 작은 글자 크기 | number | 14 |
| paddingBlock | 입력의 세로 패딩 | number | 4 |
| paddingBlockLG | 큰 입력의 세로 패딩 | number | 7 |
| paddingBlockSM | 작은 입력의 세로 패딩 | number | 0 |
| paddingInline | 입력의 가로 패딩 | number | 11 |
| paddingInlineLG | 큰 입력의 가로 패딩 | number | 11 |
| paddingInlineSM | 작은 입력의 가로 패딩 | number | 7 |
| warningActiveShadow | 경고 상태에서 활성 시 box-shadow | string | 0 0 0 2px rgba(255,215,5,0.1) |
글로벌 토큰 (Global Token)
| 토큰 이름 (Token Name) | 설명 (Description) | 타입 (Type) | 기본값 (Default Value) |
|---|---|---|---|
| borderRadius | 기본 컴포넌트의 테두리 반경 | number | |
| borderRadiusLG | LG 크기 테두리 반경이에요. Card, Modal 등 큰 테두리 반경을 가진 컴포넌트에 사용돼요. | number | |
| borderRadiusSM | SM 크기 테두리 반경이에요. Button, Input, Select 등 작은 크기의 입력 컴포넌트에 사용돼요. | number | |
| colorBgContainerDisabled | 비활성 상태에서 컨테이너의 배경색을 제어해요. | string | |
| colorBorder | 기본 테두리 색이에요. 폼 구분선, 카드 구분선처럼 서로 다른 요소를 구분하는 데 사용돼요. | string | |
| colorBorderDisabled | 비활성 상태의 요소 테두리 색을 제어해요. | string | |
| colorError | 오류 Button, 오류 Result 컴포넌트 등 작업 실패의 시각적 요소를 나타내는 데 사용돼요. | string | |
| colorErrorBg | 오류 상태의 배경색 | string | |
| colorErrorText | 오류 색에서 텍스트의 기본 상태 | string | |
| colorFillTertiary | 3단계 fill 색으로 Slider, Segmented 등 요소의 모양을 나타내는 데 사용돼요. 강조 요구가 없다면 3단계 fill 색을 기본 fill로 쓰는 걸 권장해요. | string | |
| colorText | W3C 표준을 따르는 기본 텍스트 색이에요. 가장 어두운 중성색이기도 해요. | string | |
| colorTextDisabled | 비활성 상태의 텍스트 색을 제어해요. | string | |
| colorWarning | Notification, Alert 등 경고를 나타내는 map 토큰에 사용돼요. Alert나 Input 같은 컨트롤 컴포넌트도 이 map 토큰을 사용해요. | string | |
| colorWarningBg | 경고 상태의 배경색 | string | |
| colorWarningText | 경고 색에서 텍스트의 기본 상태 | string | |
| controlHeightLG | LG 컴포넌트 높이 | number | |
| controlHeightSM | SM 컴포넌트 높이 | number | |
| fontFamily | Ant Design의 글꼴은 시스템의 기본 인터페이스 글꼴을 우선시하고, 화면 표시에 적합한 대체 글꼴 라이브러리를 제공해 플랫폼과 브라우저에 따라 가독성을 유지하며 친근하고 안정적이며 전문적인 특성을 반영해요. | string | |
| fontSize | 디자인 시스템에서 가장 널리 쓰이는 글자 크기로, 여기서 텍스트 그라데이션이 파생돼요. | number | |
| lineHeight | 텍스트의 줄 높이예요. | number | |
| lineHeightLG | 큰 텍스트의 줄 높이예요. | number | |
| lineType | 기본 컴포넌트의 테두리 스타일 | string | |
| lineWidth | 기본 컴포넌트의 테두리 두께 | number | |
| motionDurationSlow | 동작 속도, 느린 속도예요. 큰 요소의 애니메이션 상호작용에 사용돼요. | string | |
| paddingXS | 요소의 아주 작은 패딩을 제어해요. | number | |
| paddingXXS | 요소의 아주 작은 패딩을 제어해요. | number |
FAQ
prefix/suffix/showCount를 바꿀 때 Input이 포커스를 잃는 이유는 무엇인가요? {#faq-lose-focus}
Input이 prefix/suffix/showCount를 동적으로 추가하거나 제거하면 React가 dom 구조를 다시 만들고 새 input은 포커스가 되지 않아요. 빈 <span /> 요소를 설정해 dom 구조를 유지할 수 있어요.
const suffix = condition ? <Icon type="smile" /> : <span />;
<Input suffix={suffix} />;
제어(control)에서 TextArea가 value를 maxLength보다 넘게 만들 수 있는 이유는 무엇인가요? {#faq-textarea-exceed-max}
제어 상태에서는 컴포넌트가 설정된 대로 표시되어야 해요. 제출 값을 Form의 저장 값과 맞추지 못하는 문제를 피하기 위해서예요.