Select

사용자가 미리 정의된 옵션 목록 중 하나 혹은 하나 이상의 항목을 선택할 수 있는 입력 요소입니다.

@MainActor struct Select

Overview

@State private var items = [
    .init(text: "Option 1"),
    .init(text: "Option 2"),
    .init(text: "Option 3")
]

Select(
    variant: .single(selectionType: .checkmark),
    items: $items
)
.placeholder("선택하세요")

// 비활성화
Select(variant: .single(), items: $items)
    .disabled(true)

Note

비활성화는 SwiftUI 표준 disabled(_:)를 사용합니다. 상위 컨테이너에 한 번 걸면 하위 컴포넌트까지 함께 비활성 스타일로 표시됩니다.

Topics

Structures

struct Item

Select 컴포넌트에서 사용하는 항목 모델을 정의합니다.

Initializers

init(text: String, icon: Icon?, isNegative: Bool, isSelected: Bool)

아이템 초기화

  • Parameters

    ParameterDescription
    text아이템 텍스트
    icon아이템 아이콘, 생략하면 기본값으로 nil 적용
    isNegative부정적 상태 여부, 생략하면 기본값으로 false 적용
    isSelected선택 여부, 생략하면 기본값으로 false 적용

Instance Properties

let icon: Icon?

아이템의 아이콘

let isNegative: Bool

부정적 상태 여부 (오류나 경고를 나타낼 때 사용)

var isSelected: Bool

항목의 선택 여부

let text: String

아이템 텍스트 내용

Initializers

init(menuPresented: Binding<Bool>?, variant: Variant, items: Binding<[Item]>, onTapItem: ((Select.Item) -> Void)?)

Select 컴포넌트 초기화

  • Parameters

    ParameterDescription
    menuPresented메뉴 표시 상태 바인딩, 생략하면 기본값으로 nil 적용
    variant컴포넌트의 시각적/기능적 변형
    items선택 가능한 항목 배열 (바인딩)
    onTapItem항목 선택 시 호출되는 클로저, 생략하면 기본값으로 nil 적용

Instance Properties

var body: some View

뷰의 내용과 동작을 정의합니다.

  • Discussion

    항상 FormControl로 감싼다. 라벨·메시지 유무로 분기하면 값이 런타임에 바뀔 때 뷰 identity가 갈려 메뉴 표시 상태가 초기화되므로, 설정이 비어 있어도 래퍼를 유지한다.

Instance Methods

func accessory<Accessory>(() -> Accessory) -> Select

메시지 행의 오른쪽에 표시할 액세서리 뷰를 설정합니다.

  • Parameters

    ParameterDescription
    accessory표시할 액세서리 뷰 빌더

  • Return Value

    수정된 Select 인스턴스

  • Discussion

    스타일(타이포그래피·색)은 호출부에서 지정합니다.

func label(String?, required: Bool) -> Select

제목(라벨)을 붙이고 필수 표시(*) 여부를 설정합니다.

  • Parameters

    ParameterDescription
    text라벨 텍스트. nil이거나 비어 있으면 라벨을 표시하지 않습니다.
    required필수 입력 표시(*) 여부, 생략하면 기본값으로 false 적용

  • Return Value

    수정된 Select 인스턴스

  • Discussion

    이 모디파이어를 쓰면 Select가 FormControl로 감싸져 라벨·메시지·액세서리가 함께 배치됩니다.

    Select(variant: .single(), items: $regions)
    .placeholder("지역을 선택하세요")
    .label("근무 지역", required: true)

    Note

    Select는 자신의 접근성 라벨을 placeholder로 정의하므로, 라벨을 붙이면 그 값이 우선합니다.

func labelPlacement(FormControl.LabelPlacement) -> Select

라벨 위치를 설정합니다.

  • Parameters

    ParameterDescription
    placement라벨 위치, 생략하면 기본값으로 .top 적용

  • Return Value

    수정된 Select 인스턴스

func labelWidth(CGFloat) -> Select

leading 배치에서 라벨 열의 폭을 명시적으로 고정합니다.

  • Parameters

    ParameterDescription
    width라벨 열 폭(pt)

  • Return Value

    수정된 Select 인스턴스

  • Discussion

    여러 입력의 라벨 열을 한꺼번에 맞추려면 각 입력에 반복하지 말고 FormControlGroup을 사용하세요. FormControl.LabelPlacement.top 배치에는 영향이 없습니다.

func leading(Resource.Leading?) -> Select

필드 왼쪽에 표시할 요소를 지정합니다.

  • Parameters

    ParameterDescription
    leading표시할 요소, nil이면 표시하지 않음

  • Return Value

    수정된 Select 인스턴스

  • Discussion

    Select(variant: .single(), items: $items)
    .leading(.icon(.search))
func menuResize(BottomSheet.Resize) -> Select

메뉴의 높이 detent를 지정합니다.

  • Parameters

    ParameterDescription
    menuResize메뉴 크기 조정 방식

  • Return Value

    수정된 Select 인스턴스

func message(String?) -> Select

입력 아래에 표시할 도움말/에러 메시지를 설정합니다.

  • Parameters

    ParameterDescription
    text메시지 텍스트. nil이거나 비어 있으면 메시지를 표시하지 않습니다.

  • Return Value

    수정된 Select 인스턴스

  • Discussion

    메시지 색은 status(_:)에 따라 결정되며 오류 상태에서만 강조 색으로 표시됩니다.

func placeholder(String) -> Select

선택된 항목들이 없는 경우 placeholder를 표시합니다.

  • Parameters

    ParameterDescription
    placeholder표시할 플레이스홀더 텍스트

  • Return Value

    수정된 Select 인스턴스

func size(Size) -> Select

Select 컴포넌트의 사이즈를 설정합니다.

  • Parameters

    ParameterDescription
    size적용할 사이즈, 생략하면 기본값으로 .large 적용

  • Return Value

    수정된 Select 인스턴스

func status(Status) -> Select

Select 컴포넌트의 상태를 설정합니다.

  • Parameters

    ParameterDescription
    status적용할 상태

  • Return Value

    수정된 Select 인스턴스

Enumerations

enum Render

variant가 multiple일 때 컴포넌트에 표시될 내용의 형태를 결정하는 열거형입니다.

Enumeration Cases

case chip

선택된 항목을 칩(chip) 형태로 표시

case text

선택된 항목 텍스트만 표시

enum Resource

필드 안에 놓을 수 있는 요소의 프리셋입니다.

Enumerations

enum Leading

필드 왼쪽(leading(_:))에 놓는 요소입니다.

Enumeration Cases
case icon(Icon)

아이콘입니다. 크기와 색은 Select.Size에 맞춰 고정됩니다.

  • Parameters

    ParameterDescription
    icon표시할 아이콘
case iconButton(IconButton)

아이콘 버튼입니다.

  • Parameters

    ParameterDescription
    iconButton표시할 아이콘 버튼
case slotView(() -> AnyView)

프리셋에 없는 구성을 직접 그릴 때 씁니다. slot(_:)으로 만듭니다.

Type Methods
static func slot<V>(() -> V) -> Leading

프리셋에 없는 구성을 직접 그립니다.

  • Parameters

    ParameterDescription
    content왼쪽에 놓을 콘텐츠

  • Return Value

    해당 콘텐츠를 그리는 Select.Resource.Leading

enum SingleSelectionType

variant가 single일 때 아이템 선택 창에 아이템이 표시되는 방식을 결정하는 열거형입니다.

Enumeration Cases

case checkmark

체크마크로 선택 표시

case radio

라디오 버튼으로 선택 표시

enum Size

Select 컴포넌트의 사이즈를 정의합니다.

  • Overview

    사이즈에 따라 컨테이너 패딩, 모서리 반경, 최소 높이, 입력 타이포그래피, 선행 아이콘 크기가 함께 결정됩니다. TextField의 사이즈 정책과 동일합니다.

Enumeration Cases

case large

큰 사이즈 (최소 높이 48)

case medium

중간 사이즈 (최소 높이 40)

enum Status

Select 컴포넌트의 상태를 정의합니다.

Enumeration Cases

case negative

오류 상태

case normal

기본 상태

enum Variant

선택 모드를 나타내는 열거형입니다.

Enumeration Cases

case multiple(render: Render, overflow: Bool, menuPrimaryButtonTitle: String)

다중 선택 모드

  • Parameters

    ParameterDescription
    render선택된 항목 표시 방식, 생략하면 기본값으로 .text 적용
    overflow선택된 항목이 여러 줄로 표시되는지 여부, 생략하면 기본값으로 false 적용
    menuPrimaryButtonTitle확인 버튼 제목
case single(selectionType: SingleSelectionType, menuPrimaryButtonTitle: String?)

단일 선택 모드

  • Parameters

    ParameterDescription
    selectionType선택 표시 방식, 생략하면 기본값으로 .radio 적용
    menuPrimaryButtonTitle확인 버튼 제목, 생략하면 기본값으로 nil 적용 (버튼 표시 안 함)

Relationships

Conforms To

Swift.Sendable

SwiftUICore.View

© 2026 Wanted Lab, Inc.