UI 가이드

다크 모드

ScDropDown ​

ScDropDown은 리스트에서 하나의 항목을 선택할 수 있는 셀렉트(드롭다운) 컴포넌트입니다.
객체 배열을 기반으로 항목을 렌더링하며, 다양한 상태 및 레이아웃 조절이 가능합니다.

✅ 기본 사용법 ​

선택
결과 :
vue
<div class="w-[200px]">
  <sc-dropdown :items="simpleItems" v-model="simpleValue" @change="onChange" />
</div>

<div class="mt-5 text-sm">결과 : {{ simpleValue }}</div>

<script setup>
const simpleItems = [
  '규정', '규칙', 'Red', 'Blue', 'White-breasted Wood swallow', 'Black', 'Grey'
];
const simpleValue = ref('');

function onChange(val) {
  console.info('onChange', val)
}
</script>

✨ 사용 예시 모음 ​

▸ defaultValue 기본값 option 추가 ​

검색조건에서 dropdown 사용시 ALL 이라고 기본값을 따로 설정할수 있고 전체검색값으로는 빈값으로 사용할 수도 있어서 그래서 default-value 값을 '' 로 설정하면 위와 같은 항목을 만들어 주는 역할

ALL
결과 :
vue
<div class="w-[150px]">
  <!-- option 에 ALL 생김 value는 '' 빈 값 String -->
  <sc-dropdown :items="simpleItems" v-model="dfValue1" placeholder="ALL" default-value />
</div>
<div class="mt-5 text-sm">결과 : {{ dfValue1 }}</div>

<script setup>
const dfValue1 = ref('');
</script>
전체
결과 : all
vue
<div class="w-[150px] mt-5">
  <!-- option 에 전체 생김 value는 'all' -->
  <sc-dropdown :items="items" v-model="dfValue2" placeholder="전체" default-value="all" />
</div>
<div class="mt-5 text-sm">결과 : {{ dfValue2 }}</div>

<script setup>
  const dfValue2 = ref('all');
</script>

▸ borderless 테두리 없애기 ​

100 개
결과 : 100
vue
<div class="w-[100px] mt-5">
  <sc-dropdown :items="pageItems" v-model="pageValue" borderless />
</div>

<div class="mt-5 text-sm">결과 : {{ pageValue }}</div>
<script setup>
const pageItems = [
  { value: '100', text: '100 개' },
  { value: '300', text: '300 개' },
  { value: '500', text: '500 개' },
  { value: '1000', text: '1000 개' }
];
const pageValue = ref('100');
</script>

▸ item 항목이 Object 형태인 경우 ​

items의 키 값인 value와 라벨 값인 text로 select 영역을 만듭니다.

선택
결과 :
vue
<div class="w-[150px]">
  <sc-dropdown :items="items" v-model="value" @change="onChange" />
</div>
<div class="mt-5 text-sm">결과 : {{ value }}</div>

<script setup>
const items = [
  { value: 'COC', text: 'Cockatoo' },
  { value: 'MAG', text: 'Magpie Goose' },
  { value: 'LIT', text: 'Little Kingfisher' },
  { value: 'RIC', text: "Richard's Pipit" }
];
const value = ref('');
</script>

▸ item의 Custom Key 사용 ​

기본 키값이 아닌 custom 하게 Object의 키 값을 지정할 수 있습니다. 아래 예제는 Key 값은 code 라벨 값은 name 으로 지정했습니다.

선택
결과 :
vue
<div class="w-[150px]">
  <sc-dropdown
    :items="items2"
    v-model="value2"
    item-value="code"
    item-text="name"
    @change="onChange"
  />
</div>
<div class="mt-5 text-sm">결과 : {{ value2 }}</div>

<script setup>
const items2 = [
  { code: 'A', name: 'A CODE' },
  { code: 'B', name: 'B CODE' },
  { code: 'C', name: 'C CODE' }
];
const value2 = ref('');
</script>

▸ searchable 검색 ​

:searchable - 선택 가능한 항목을 검색 가능

- 키보드 Up, Down과 Enter를 이용 하여 선택 가능

- 검색어를 입력하여 조건이 한개인 경우 Enter를 입력하면 선택

선택
결과 :
vue
<div class="w-[150px]">
  <sc-dropdown
    :items="simpleItems"
    v-model="dfValue1"
    searchable
    default-value
    @change="onChange"
    :tooltip-show-length="10"
  />
</div>
<div class="mt-5 text-sm">결과 : {{ dfValue1 }}</div>

▸ disabled 비활성화 ​

선택
vue
<div class="w-[200px]">
  <sc-dropdown :items="simpleItems" v-model="simpleValue" disabled="" />
</div>

🛠️ 속성 (Props) ​

이름타입기본값설명
itemsArray[]드롭다운에 표시할 항목 목록
modelValuestring | number | boolean''선택된 값 (v-model)
placeholderstring'선택'입력 안내 문구
defaultValueboolean | object | stringfalse초기 선택할 기본 값
disabledbooleanfalse전체 비활성화 여부
sizestring ('', small, medium, large)'medium'크기 설정
rightbooleanfalse드롭다운 오른쪽 정렬 여부
roundedbooleanfalse테두리를 둥글게 표시
itemTextstring'text'항목 객체에서 라벨로 사용할 필드명
itemValuestring'value'항목 객체에서 값으로 사용할 필드명
borderlessbooleanfalse테두리 없음
searchablebooleanfalse항목 검색 기능 활성화 여부
rulesArray[]유효성 검사 규칙 목록
firstSelectbooleanfalse첫 번째 항목 자동 선택 여부
tooltipShowLengthnumber-1텍스트 길이 제한 시 툴팁 표시 기준

📤 이벤트 (Emits) ​

이벤트 이름설명
update:modelValue선택된 값 변경 시 발생 (v-model)
change선택 변경 시 사용자 정의 로직 수행
changeObject전체 객체 반환 시 발생

🔳 슬롯 (Slots) ​

이 컴포넌트는 슬롯을 사용하지 않습니다.

🎨 스타일 클래스 ​

클래스 이름설명
sc-drop-down기본 wrapper
sc-drop-down--disabled비활성화 상태
sc-drop-down--readonly읽기 전용 상태
sc-drop-down--blockblock 모드 적용 시
sc-drop-down--smallsmall 크기 클래스
sc-drop-down--mediummedium 크기 클래스
sc-drop-down--largelarge 크기 클래스
sc-drop-down--borderless테두리 없음 적용 시

📝 기타 참고사항 ​

  • itemText, itemValue로 label/value 매핑 필드명을 동적으로 지정할 수 있습니다.
  • searchable이 true일 경우 입력 기반 실시간 필터링이 가능합니다.
  • tooltipShowLength는 항목 텍스트 길이가 지정값을 초과할 경우 툴팁을 표시합니다.
  • rules를 활용해 유효성 검증 로직을 연동할 수 있습니다.