Select셀렉트

드롭다운 셀렉트 컴포넌트는 드롭다운 메뉴에 다양한 옵션을 제공하여 사용자가 필요한 내용을 빠르게 선택할 수 있도록 합니다.

이 페이지는 주로 <mdui-select> 컴포넌트의 사용법을 소개하며, 드롭다운 메뉴 항목의 사용법은 <mdui-menu-item>을 참조하세요.

사용법

컴포넌트 가져오기:

import 'mdui/components/select.js';
import 'mdui/components/menu-item.js';

컴포넌트의 TypeScript 타입 가져오기:

import type { Select } from 'mdui/components/select.js';
import type { MenuItem } from 'mdui/components/menu-item.js';

사용 예시:

Item 1

Item 2

<mdui-select value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

예시

형태

variant 속성으로 드롭다운 셀렉트의 형태를 설정합니다.

Item 1

Item 2

Item 1

Item 2

<mdui-select variant="filled" value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

<mdui-select variant="outlined" value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

소스

다중 선택 지원

드롭다운 셀렉트는 기본적으로 단일 선택이며, <mdui-select> 컴포넌트의 value 값은 현재 선택된 <mdui-menu-item>의 value 값입니다.

multiple 속성을 추가하면 드롭다운 셀렉트가 다중 선택을 지원합니다. 이때 <mdui-select>의 value 값은 현재 선택된 <mdui-menu-item>의 value 값으로 구성된 배열입니다.

참고: 다중 선택 지원 시 <mdui-select>의 value 값은 배열이므로 JavaScript 속성으로서만 값을 읽고 설정할 수 있습니다.

Item 1

Item 2

Item 3

<mdui-select multiple class="example-multiple">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
  <mdui-menu-item value="item-3">Item 3</mdui-menu-item>
</mdui-select>

<script>
  // item-1과 item-2를 기본 선택으로 설정
  const select = document.querySelector(".example-multiple");
  select.value = ["item-1", "item-2"];
</script>

소스

보조 텍스트

label 속성을 사용해 드롭다운 셀렉트 상단의 레이블 텍스트를 설정합니다.

Item 1

Item 2

<mdui-select label="Text Field" value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

소스

placeholder 속성을 사용해 값이 선택되지 않았을 때의 플레이스홀더 텍스트를 설정합니다.

Item 1

Item 2

<mdui-select placeholder="Placeholder">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

소스

helper 속성을 사용해 드롭다운 셀렉트 하단의 도움말 텍스트를 설정합니다. helper 슬롯을 사용해 도움말 텍스트를 설정할 수도 있습니다.

Item 1

Item 2

Item 1

Item 2

Supporting text

<mdui-select helper="Supporting text">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

<mdui-select>
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
  <span slot="helper" style="color: blue">Supporting text</span>
</mdui-select>

소스

읽기 전용 모드

readonly 속성을 추가하면 드롭다운 셀렉트를 읽기 전용 모드로 설정할 수 있습니다.

Item 1

Item 2

<mdui-select readonly value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

소스

비활성화 모드

disabled 속성을 추가하면 드롭다운 셀렉트를 비활성화할 수 있습니다.

Item 1

Item 2

<mdui-select disabled value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

소스

비우기 가능

clearable 속성을 추가하면 드롭다운 셀렉트에 값이 있을 때 오른쪽에 비우기 버튼이 나타납니다.

Item 1

Item 2

<mdui-select clearable value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

소스

clear 슬롯을 통해 비우기 버튼을 사용자 정의할 수도 있습니다.

Item 1

Item 2

<mdui-select clearable value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
  <mdui-icon slot="clear" name="delete"></mdui-icon>
</mdui-select>

소스

드롭다운 메뉴 위치

placement 속성으로 드롭다운 메뉴의 위치를 설정할 수 있습니다.

Item 1

Item 2

<mdui-select placement="top" value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

소스

텍스트 오른쪽 정렬

end-aligned 속성을 추가하면 텍스트를 오른쪽으로 정렬할 수 있습니다.

Item 1

Item 2

<mdui-select end-aligned value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

소스

앞뒤 텍스트 및 아이콘

icon 및 end-icon 속성을 설정하면 드롭다운 셀렉트의 왼쪽과 오른쪽에 Material Icons 아이콘을 추가할 수 있습니다. icon 및 end-icon 슬롯을 통해 드롭다운 셀렉트의 왼쪽과 오른쪽에 요소를 추가할 수도 있습니다.

Item 1

Item 2

Item 1

Item 2

<mdui-select value="item-1" icon="search" end-icon="mic">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

<br/><br/>

<mdui-select value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
  <mdui-button-icon slot="icon" icon="search"></mdui-button-icon>
  <mdui-button-icon slot="end-icon" icon="mic"></mdui-button-icon>
</mdui-select>

소스

prefix 및 suffix 속성을 설정하면 드롭다운 셀렉트의 왼쪽과 오른쪽에 텍스트를 추가할 수 있습니다. prefix 및 suffix 슬롯을 통해 드롭다운 셀렉트의 왼쪽과 오른쪽에 텍스트 요소를 추가할 수도 있습니다. 이 텍스트는 드롭다운 셀렉트가 포커스를 받거나 값이 있을 때만 표시됩니다.

Item 1

Item 2

Item 1

Item 2

$ /100

<mdui-select value="item-1" prefix="$" suffix="/100">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
</mdui-select>

<br/><br/>

<mdui-select value="item-1">
  <mdui-menu-item value="item-1">Item 1</mdui-menu-item>
  <mdui-menu-item value="item-2">Item 2</mdui-menu-item>
  <span slot="prefix" style="color: blue">$</span>
  <span slot="suffix" style="color: blue">/100</span>
</mdui-select>

소스

API

속성

HTML 속성	JavaScript 프로퍼티	유형	기본값
`variant`	`variant`	`'filled' \| 'outlined'`	`'filled'`
셀렉트의 스타일입니다. 사용 가능한 값은 다음과 같습니다: `filled`: 배경색이 채워진 셀렉트, 시각적 강조 효과가 높습니다. `outlined`: 테두리가 있는 셀렉트, 시각적 강조 효과가 낮습니다.
`multiple`	`multiple`	`boolean`	`false`
다중 선택을 지원할지 여부를 설정합니다.
`name`	`name`	`string`	`''`
셀렉트의 이름이며, 폼 데이터와 함께 제출됩니다.
`value`	`value`	`string \| string[]`	`''`
셀렉트의 값이며, 폼 데이터와 함께 제출됩니다. `multiple` 속성을 지정하지 않으면 이 값은 문자열입니다. `multiple` 속성을 지정하면 이 값은 문자열 배열입니다. HTML 속성은 문자열 값만 설정할 수 있습니다. 배열 값을 설정해야 하는 경우 JavaScript 프로퍼티를 통해 설정하십시오.
	`defaultValue`	`string \| string[]`	`''`
기본 선택 값입니다. 폼을 재설정할 때 이 기본값으로 재설정됩니다. 이 프로퍼티는 JavaScript 프로퍼티로만 설정할 수 있습니다.
`label`	`label`	`string`	-
레이블 텍스트입니다.
`placeholder`	`placeholder`	`string`	-
플레이스홀더 텍스트입니다.
`helper`	`helper`	`string`	-
셀렉트 하단의 도움말 텍스트입니다. `slot="helper"`을 통해서도 설정할 수 있습니다.
`clearable`	`clearable`	`boolean`	`false`
셀렉트를 비울 수 있는지 여부를 설정합니다.
`clear-icon`	`clearIcon`	`string`	-
셀렉트를 비울 수 있을 때 셀렉트 오른쪽에 표시되는 지우기 버튼의 Material Icons 아이콘 이름입니다. `slot="clear-icon"`을 통해서도 설정할 수 있습니다.
`placement`	`placement`	`'auto' \| 'bottom' \| 'top'`	`'auto'`
셀렉트의 위치입니다. 사용 가능한 값: `auto`: 위치 자동 판단 `bottom`: 아래쪽에 위치 `top`: 위쪽에 위치
`end-aligned`	`endAligned`	`boolean`	`false`
텍스트를 오른쪽 정렬할지 여부를 설정합니다.
`prefix`	`prefix`	`string`	-
셀렉트의 접두사 텍스트입니다. 포커스 상태이거나 셀렉트에 값이 있을 때만 표시됩니다. `slot="prefix"`을 통해서도 설정할 수 있습니다.
`suffix`	`suffix`	`string`	-
셀렉트의 접미사 텍스트입니다. 포커스 상태이거나 셀렉트에 값이 있을 때만 표시됩니다. `slot="suffix"`을 통해서도 설정할 수 있습니다.
`icon`	`icon`	`string`	-
셀렉트 앞쪽 아이콘의 Material Icons 아이콘 이름입니다. `slot="icon"`을 통해서도 설정할 수 있습니다.
`end-icon`	`endIcon`	`string`	-
셀렉트 뒤쪽 아이콘의 Material Icons 아이콘 이름입니다. `slot="end-icon"`을 통해서도 설정할 수 있습니다.
`error-icon`	`errorIcon`	`string`	-
폼 필드 유효성 검사 실패 시 셀렉트 오른쪽에 표시되는 Material Icons 아이콘 이름입니다. `slot="error-icon"`을 통해서도 설정할 수 있습니다.
`form`	`form`	`string`	-
연결된 `<form>` 요소입니다. 이 속성 값은 동일한 페이지에 있는 `<form>` 요소의 `id`여야 합니다. 이 속성을 지정하지 않으면 이 요소는 `<form>` 요소의 자식 요소여야 합니다. 이 속성을 사용하면 요소를 `<form>` 요소의 자식뿐만 아니라 페이지의 어느 곳에나 배치할 수 있습니다.
`readonly`	`readonly`	`boolean`	`false`
읽기 전용 여부를 설정합니다.
`disabled`	`disabled`	`boolean`	`false`
비활성화할지 여부를 설정합니다.
`required`	`required`	`boolean`	`false`
폼 제출 시 이 필드가 필수인지 여부를 설정합니다.
	`validity`	`ValidityState`	-
폼 유효성 검사 상태 객체입니다. 자세한 내용은 `ValidityState`를 참조하십시오.
	`validationMessage`	`string`	-
폼 유효성 검사를 통과하지 못하면 오류 메시지가 포함되고, 통과하면 빈 문자열입니다.
`autofocus`	`autofocus`	`boolean`	`false`
페이지 로드 후 자동으로 포커스를 받을지 여부를 지정합니다.
`tabindex`	`tabIndex`	`number`	-
Tab 키를 사용하여 포커스를 이동할 때 요소의 순서를 지정합니다.

메서드

이름	매개변수	반환값
`checkValidity`		`boolean`
폼 필드가 유효성 검사를 통과하는지 확인합니다. 통과하지 못하면 `false`를 반환하고 `invalid` 이벤트를 트리거합니다. 통과하면 `true`를 반환합니다.
`reportValidity`		`boolean`
폼 필드가 유효성 검사를 통과하는지 확인합니다. 통과하지 못하면 `false`를 반환하고 `invalid` 이벤트를 트리거합니다. 통과하면 `true`를 반환합니다. 유효성 검사를 통과하지 못하면 컴포넌트에 유효성 검사 실패 메시지가 표시됩니다.
`setCustomValidity`	`message: string`	`void`
사용자 정의 오류 메시지 텍스트를 설정합니다. 이 텍스트가 비어 있지 않으면 필드가 유효성 검사를 통과하지 못했음을 나타냅니다.
`click`		`void`
마우스 클릭을 시뮬레이션합니다.
`focus`	`options: FocusOptions` (선택사항)	`void`
현재 요소에 포커스를 설정합니다. 객체를 인자로 전달할 수 있으며, 객체의 속성은 다음과 같습니다: `preventScroll`: 기본적으로 요소가 포커스를 받으면 페이지가 스크롤되어 해당 요소가 화면에 표시됩니다. 페이지 스크롤을 방지하려면 이 속성을 `true`로 설정하십시오.
`blur`		`void`
현재 요소에서 포커스를 제거합니다.

이벤트

이름
`focus`
포커스를 얻었을 때 발생합니다.
`blur`
포커스를 잃었을 때 발생합니다.
`change`
선택된 값이 변경될 때 발생합니다.
`invalid`
폼 필드 유효성 검사를 통과하지 못했을 때 발생합니다.
`clear`
`clearable` 속성으로 생성된 지우기 버튼을 클릭할 때 발생합니다. `event.preventDefault()`를 호출하여 셀렉트 비우기를 막을 수 있습니다.

Slots

이름
기본
`<mdui-menu-item>` 요소
`icon`
왼쪽 아이콘
`end-icon`
오른쪽 아이콘
`error-icon`
유효성 검사 실패 상태의 오른쪽 아이콘
`prefix`
왼쪽 텍스트
`suffix`
오른쪽 텍스트
`clear-button`
지우기 버튼
`clear-icon`
지우기 버튼 내의 아이콘
`helper`
하단의 도움말 텍스트

CSS Parts

이름
`chips`
다중 선택 시 선택된 값에 해당하는 칩을 배치하는 컨테이너
`chip`
다중 선택 시 각 선택된 값에 해당하는 칩
`chip__button`
칩 내부의 `<button>` 요소
`chip__label`
칩 내부의 텍스트
`chip__delete-icon`
칩 내부의 삭제 아이콘
`text-field`
텍스트 필드, 즉 `<mdui-text-field>` 요소
`text-field__container`
text-field 내부의 텍스트 필드 컨테이너
`text-field__icon`
text-field 내부의 왼쪽 아이콘
`text-field__end-icon`
text-field 내부의 오른쪽 아이콘
`text-field__error-icon`
text-field 내부의 유효성 검사 실패 상태의 오른쪽 아이콘
`text-field__prefix`
text-field 내부의 왼쪽 텍스트
`text-field__suffix`
text-field 내부의 오른쪽 텍스트
`text-field__label`
text-field 내부의 레이블 텍스트
`text-field__input`
text-field 내부의 `<input>` 요소
`text-field__clear-button`
text-field 내부의 지우기 버튼
`text-field__clear-icon`
text-field 내부의 지우기 버튼 내의 아이콘
`text-field__supporting`
text-field 내부의 하단 보조 정보 컨테이너(helper 및 error 포함)
`text-field__helper`
text-field 내부의 하단 도움말 텍스트
`text-field__error`
text-field 내부의 하단 오류 설명 텍스트
`menu`
드롭다운 메뉴, 즉 `<mdui-menu>` 요소

이전 장

RangeSlider 범위 슬라이더

다음 장

SegmentedButton 세그먼트 버튼