Segmented control

옵션들을 수평으로 나열한 버튼 그룹으로 한 번에 하나의 옵션만 선택합니다. 선택된 항목은 시각적으로 강조 되는 형태의 구조로 같은 콘텐츠 영역 내에서 보기 방식이나 필터를 변경할 때 사용됩니다.

@MainActor struct SegmentedControl

Overview

제한된 옵션 세트 내에서 선택할 수 있도록 하는 가로로 정렬된 버튼 그룹입니다. 각 세그먼트는 이미지와 텍스트를 포함할 수 있으며, 선택된 세그먼트는 시각적으로 강조됩니다.

@State private var selectedIndex = 0

// 텍스트만 있는 세그먼트 컨트롤
SegmentedControl(
    selectedIndex: $selectedIndex,
    labels: ["첫 번째", "두 번째", "세 번째"]
)

// 이미지와 텍스트가 모두 있는 세그먼트 컨트롤
SegmentedControl(
    selectedIndex: $selectedIndex,
    items: [
        .init(leadingIcon: .icon(.home), title: "홈"),
        .init(leadingIcon: .icon(.person), title: "프로필"),
        .init(title: "설정")
    ]
)
.size(.medium)

// 아이콘만 표시하는 세그먼트 컨트롤 (세그먼트 너비/높이 고정)
SegmentedControl(
    selectedIndex: $selectedIndex,
    items: [
        .init(leadingIcon: .icon(.home), title: "홈"),
        .init(leadingIcon: .icon(.person), title: "프로필")
    ]
)
.iconOnly()

Topics

Structures

struct Item

세그먼트 컨트롤의 항목을 나타내는 구조체입니다.

  • Overview

    각 항목은 이미지(선택 사항)와 텍스트로 구성됩니다.

Initializers

init(leadingIcon: Image?, title: String)

세그먼트 항목을 초기화합니다.

  • Parameters

    ParameterDescription
    leadingIcon텍스트 앞에 표시할 아이콘, 생략하면 기본값으로 nil 적용
    title표시할 텍스트. iconOnly 모드에서는 텍스트가 숨겨지는 대신 이 값이 세그먼트의 VoiceOver 접근성 라벨로 사용됩니다.

Initializers

init(selectedIndex: Binding<Int>, items: [Item], onSelect: ((Int) -> Void)?)

항목 배열을 이용해 세그먼트 컨트롤을 초기화합니다.

  • Parameters

    ParameterDescription
    selectedIndex현재 선택된 항목의 인덱스 바인딩
    items표시할 항목 배열
    onSelect항목 선택 시 호출될 클로저, 생략하면 기본값으로 nil 적용
init(selectedIndex: Binding<Int>, labels: [String], onSelect: ((Int) -> Void)?)

텍스트 배열을 이용해 세그먼트 컨트롤을 초기화합니다.

  • Parameters

    ParameterDescription
    selectedIndex현재 선택된 항목의 인덱스 바인딩
    labels표시할 텍스트 배열
    onSelect항목 선택 시 호출될 클로저, 생략하면 기본값으로 nil 적용

Instance Properties

var body: some View

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

Instance Methods

func iconOnly(Bool) -> SegmentedControl

각 세그먼트를 아이콘만 표시하도록 설정합니다.

  • Parameters

    ParameterDescription
    iconOnly아이콘만 표시할지 여부, 생략하면 기본값으로 true 적용

  • Return Value

    수정된 세그먼트 컨트롤 인스턴스

  • Discussion

    true이면 텍스트를 숨기고 아이콘만 표시하며, 각 세그먼트의 너비와 높이가 크기별로 고정됩니다. 이 경우 각 SegmentedControl.Item에 이미지를 지정해야 하며, SegmentedControl.Item의 title은 세그먼트의 VoiceOver 접근성 라벨로 사용됩니다.

func size(Size) -> SegmentedControl

세그먼트 컨트롤의 크기를 설정합니다.

  • Parameters

    ParameterDescription
    size적용할 크기

  • Return Value

    수정된 세그먼트 컨트롤 인스턴스

Enumerations

enum Size

세그먼트 컨트롤의 크기를 정의하는 열거형입니다.

  • Overview

    크기에 따라 높이, 모서리 반경, 패딩, 타이포그래피, 아이콘 크기가 함께 결정됩니다.

Enumeration Cases

case large

큰 크기 (높이 48)

case medium

중간 크기 (높이 40)

case small

작은 크기 (높이 32)

Relationships

Conforms To

Swift.Sendable

SwiftUICore.View

© 2026 Wanted Lab, Inc.