Text area

필드 내부에 2줄 이상의 텍스트를 입력할 때 사용하며 Heading, Placeholder, Description등의 요소를 활용하여 사용자가 입력할 내용의 형식을 보다 명확하게 안내합니다.

@MainActor struct TextArea

Overview

이 컴포넌트는 사용자가 여러 줄의 텍스트를 입력할 수 있는 영역을 제공합니다. 사이즈, 리사이즈 옵션, 하단 리소스 등 다양한 기능을 지원합니다.

@State private var longText = ""
@FocusState private var isFocused: Bool

// 기본 텍스트 영역
TextArea(text: $longText, focus: $isFocused)
    .placeholder("의견을 입력해주세요")

// 중간 사이즈와 고정 크기를 가진 텍스트 영역
TextArea(text: $longText)
    .size(.medium)
    .resize(.fixed(min: 108, max: 200))

// 입력 글자 수를 추적하는 텍스트 영역
@State private var characterCount = 0
TextArea(text: $longText)
    .maxLength(100)
    .onTextChange { characterCount = $0.count }

// 자동수정·맞춤법 검사를 끈 텍스트 영역
TextArea(text: $longText)
    .autocorrectionDisabled()

// 비활성화
TextArea(text: $longText)
    .disabled(true)

Note

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

Topics

Initializers

init(text: Binding<String>, focus: FocusState<Bool>.Binding?)

텍스트 영역을 초기화합니다.

  • Parameters

    ParameterDescription
    text텍스트 영역의 값을 바인딩
    focus텍스트 영역의 포커스 상태를 바인딩, 생략하면 기본값으로 nil 적용

Instance Properties

var body: some View

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

  • Discussion

    항상 FormControl로 감싼다. 라벨·메시지 유무로 분기하면 값이 런타임에 바뀔 때 뷰 identity가 갈려 입력 중 포커스가 풀리므로, 설정이 비어 있어도 래퍼를 유지한다.

Instance Methods

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

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

  • Parameters

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

  • Return Value

    수정된 텍스트 영역 인스턴스

  • Discussion

    입력 바깥 아래에 붙는 보조 요소입니다. 입력 상자 안쪽 하단에 요소를 배치하려면 bottomResources(leading:trailing:leadingResourceSpacing:trailingResourceSpacing:)를 사용하세요.

func autocorrectionDisabled(Bool) -> TextArea

자동수정과 맞춤법 검사를 비활성화할지 설정합니다.

  • Parameters

    ParameterDescription
    disable비활성화 여부, 생략하면 기본값으로 true 적용

  • Return Value

    수정된 텍스트 영역 인스턴스

  • Discussion

    코드 조각·고유명사처럼 사전에 없는 텍스트를 자주 입력하는 화면에서 사용합니다. true이면 입력 중 자동수정이 적용되지 않고, 맞춤법 검사 밑줄도 표시되지 않습니다.

    텍스트 영역의 입력부는 UITextView를 감싼 뷰이므로 SwiftUI의 autocorrectionDisabled(_:)를 인스턴스 바깥에 붙여도 입력부까지 전달되지 않습니다. 반드시 이 모디파이어로 설정해 주세요.

func bottomResources(leading: [Resource.Leading], trailing: [Resource.Trailing], leadingResourceSpacing: CGFloat?, trailingResourceSpacing: CGFloat?) -> TextArea

텍스트 영역 하단에 표시할 UI 요소를 설정합니다.

  • Parameters

    ParameterDescription
    leading왼쪽에 표시할 UI 요소 배열 (최대 3개)
    trailing오른쪽에 표시할 UI 요소 배열 (최대 3개)
    leadingResourceSpacing왼쪽 요소 간의 간격, 생략하면 사이즈별 기본값(large 8 / medium 6) 적용
    trailingResourceSpacing오른쪽 요소 간의 간격, 생략하면 사이즈별 기본값(large 8 / medium 6) 적용

  • Return Value

    수정된 텍스트 영역 인스턴스

  • Discussion

    Note

    button·primaryIconButton은 디자인 가이드상 trailing 전용이므로 TextArea.Resource.Trailing에만 정의되어 있습니다. leading에 넘기면 컴파일되지 않습니다.

func inputTransform(((String) -> String)?) -> TextArea

입력되는 텍스트를 입력 시점에 변환할 클로저를 설정합니다.

  • Parameters

    ParameterDescription
    transform입력 조각을 변환하는 클로저, nil이면 변환하지 않음

  • Return Value

    수정된 텍스트 영역 인스턴스

  • Discussion

    사용자가 입력하거나 붙여넣는 텍스트(replacement) 조각에 적용됩니다. emoji 제거 등 도메인별 정규화에 사용합니다. 사후 변형이 아닌 입력 단계에서 적용되므로 UITextView의 텍스트와 UndoManager가 일관되게 유지됩니다.

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

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

  • Parameters

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

  • Return Value

    수정된 텍스트 영역 인스턴스

  • Discussion

    이 모디파이어를 쓰면 텍스트 영역이 FormControl로 감싸져 라벨·메시지·액세서리가 함께 배치되고, 라벨이 입력의 접근성 라벨로 연결됩니다.

    TextArea(text: $bio)
    .placeholder("자기소개를 입력하세요")
    .label("자기소개")
    .message("200자 이내로 작성해 주세요.")
func labelPlacement(FormControl.LabelPlacement) -> TextArea

라벨 위치를 설정합니다.

  • Parameters

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

  • Return Value

    수정된 텍스트 영역 인스턴스

  • Discussion

    Note

    .leading 배치에서 라벨은 입력 전체가 아니라 첫 줄 중앙에 정렬됩니다.

func labelWidth(CGFloat) -> TextArea

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

  • Parameters

    ParameterDescription
    width라벨 열 폭(pt)

  • Return Value

    수정된 텍스트 영역 인스턴스

  • Discussion

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

func maxLength(Int?) -> TextArea

최대 글자 수를 설정합니다.

  • Parameters

    ParameterDescription
    limit최대 글자 수, nil이면 제한 없음

  • Return Value

    수정된 텍스트 영역 인스턴스

  • Discussion

    카운터 UI를 표시하지 않고 입력 길이만 제한합니다. 사후 변형이 아닌 입력 단계에서 제한하므로 UITextView의 텍스트와 UndoManager가 일관되게 유지되며, 초과 입력/붙여넣기는 허용분만 잘라서 삽입됩니다.

func message(String?) -> TextArea

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

  • Parameters

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

  • Return Value

    수정된 텍스트 영역 인스턴스

  • Discussion

    메시지 색은 negative(_:)에 따라 결정되며 오류 상태에서만 강조 색으로 표시됩니다. 메시지는 입력의 접근성 힌트로도 연결됩니다.

func negative(Bool) -> TextArea

텍스트 영역의 오류 상태를 설정합니다.

  • Parameters

    ParameterDescription
    negative오류 상태 여부, 생략하면 기본값으로 true 적용

  • Return Value

    수정된 텍스트 영역 인스턴스

  • Discussion

    오류 상태일 때는 텍스트 영역이 적색 테두리로 강조됩니다.

func onTextChange((String) -> Void) -> TextArea

텍스트가 변경될 때마다 호출할 클로저를 설정합니다.

  • Parameters

    ParameterDescription
    handler변경된 텍스트를 전달받는 클로저

  • Return Value

    수정된 텍스트 영역 인스턴스

  • Discussion

    변경된 전체 텍스트를 전달하므로 글자 수 계산(text.count), 유효성 검사 등 다양한 후처리에 사용할 수 있습니다.

func placeholder(String?) -> TextArea

텍스트 영역에 입력된 텍스트가 없을 때 표시할 플레이스홀더를 설정합니다.

  • Parameters

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

  • Return Value

    수정된 텍스트 영역 인스턴스

func resize(Resize) -> TextArea

텍스트 영역의 크기 조절 방식을 설정합니다.

  • Parameters

    ParameterDescription
    resize크기 조절 방식

  • Return Value

    수정된 텍스트 영역 인스턴스

func size(Size) -> TextArea

텍스트 영역의 사이즈를 설정합니다.

  • Parameters

    ParameterDescription
    size텍스트 영역의 사이즈

  • Return Value

    수정된 텍스트 영역 인스턴스

Enumerations

enum Resize

텍스트 영역의 크기 조절 방식을 정의합니다.

Enumeration Cases

case fixed(min: CGFloat, max: CGFloat)

텍스트 영역의 최소 및 최대 높이를 지정합니다. 초과 부분은 스크롤할 수 있습니다.

  • Parameters

    ParameterDescription
    min최소 높이
    max최대 높이
case limit

최대 6줄까지 표시되며, 초과 부분은 스크롤할 수 있습니다. 최소 높이는 2줄 기준입니다.

case normal

줄 수 제한이 없으며, 입력된 텍스트에 따라 영역이 자동으로 확장됩니다. 최소 높이는 2줄 기준입니다.

enum Resource

텍스트 영역 하단(Bottom Content)에 표시할 요소들의 Namespace입니다.

Enumerations

enum Leading

Bottom Content 왼쪽에 표시할 요소입니다.

Enumeration Cases
case contentBadge(ContentBadge.Variant, title: String)

콘텐츠 뱃지

  • Parameters

    ParameterDescription
    variant뱃지 변형 스타일, 생략하면 기본값으로 .solid 적용
    title뱃지 텍스트
case icon(Icon, tintColor: SwiftUI.Color)

단순 아이콘

  • Parameters

    ParameterDescription
    icon표시할 아이콘
    tintColor아이콘 색상, 생략하면 기본값으로 .semantic(.foregroundNeutralQuaternary) 적용
case iconButton(icon: Icon, tintColor: SwiftUI.Color, handler: (() -> Void)?)

아이콘 버튼(배경 없음)

  • Parameters

    ParameterDescription
    icon버튼 아이콘
    tintColor아이콘 색상, 생략하면 기본값으로 .semantic(.foregroundNeutralTertiary) 적용
    handler버튼 클릭 핸들러, 생략하면 기본값으로 nil 적용
case segmentedControl(selectedIndex: Binding<Int>, icons: [Icon], accessibilityLabels: [String], onSelect: ((Int) -> Void)?)

세그먼트 컨트롤(아이콘 전용). 표준 SegmentedControl을 small 크기·iconOnly로 렌더링하며 정방형 아이콘만 받습니다.

  • Parameters

    ParameterDescription
    selectedIndex선택된 세그먼트 인덱스 바인딩
    icons세그먼트 아이콘 배열
    accessibilityLabels세그먼트별 VoiceOver 라벨 배열, 생략하면 기본값으로 [] 적용
    onSelect선택 변경 핸들러, 생략하면 기본값으로 nil 적용

  • Discussion

    accessibilityLabels는 각 세그먼트의 항목 제목으로 전달됩니다. 라벨을 생략하거나 개수가 부족하면 해당 세그먼트는 아이콘 이름으로 대체됩니다.

case slotView(() -> AnyView)

임의 뷰. slot(_:) 팩토리로 생성합니다.

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

목록에 없는 구성을 직접 배치합니다.

  • Parameters

    ParameterDescription
    content표시할 뷰를 생성하는 클로저

  • Return Value

    구성된 요소

enum Trailing

Bottom Content 오른쪽에 표시할 요소입니다.

Enumeration Cases
case button(color: Button.Color, title: String, handler: (() -> Void)?)

텍스트 버튼(Outlined)

  • Parameters

    ParameterDescription
    color버튼 색상, 생략하면 기본값으로 .assistive 적용
    title버튼 텍스트
    handler버튼 클릭 핸들러, 생략하면 기본값으로 nil 적용
case contentBadge(ContentBadge.Variant, title: String)

콘텐츠 뱃지

  • Parameters

    ParameterDescription
    variant뱃지 변형 스타일, 생략하면 기본값으로 .solid 적용
    title뱃지 텍스트
case icon(Icon, tintColor: SwiftUI.Color)

단순 아이콘

  • Parameters

    ParameterDescription
    icon표시할 아이콘
    tintColor아이콘 색상, 생략하면 기본값으로 .semantic(.foregroundNeutralQuaternary) 적용
case iconButton(icon: Icon, tintColor: SwiftUI.Color, handler: (() -> Void)?)

아이콘 버튼(배경 없음)

  • Parameters

    ParameterDescription
    icon버튼 아이콘
    tintColor아이콘 색상, 생략하면 기본값으로 .semantic(.foregroundNeutralTertiary) 적용
    handler버튼 클릭 핸들러, 생략하면 기본값으로 nil 적용
case primaryIconButton(icon: Icon, handler: (() -> Void)?)

Primary 아이콘 버튼(Solid)

  • Parameters

    ParameterDescription
    icon버튼 아이콘
    handler버튼 클릭 핸들러, 생략하면 기본값으로 nil 적용
case segmentedControl(selectedIndex: Binding<Int>, icons: [Icon], accessibilityLabels: [String], onSelect: ((Int) -> Void)?)

세그먼트 컨트롤(아이콘 전용). 표준 SegmentedControl을 small 크기·iconOnly로 렌더링하며 정방형 아이콘만 받습니다.

  • Parameters

    ParameterDescription
    selectedIndex선택된 세그먼트 인덱스 바인딩
    icons세그먼트 아이콘 배열
    accessibilityLabels세그먼트별 VoiceOver 라벨 배열, 생략하면 기본값으로 [] 적용
    onSelect선택 변경 핸들러, 생략하면 기본값으로 nil 적용

  • Discussion

    accessibilityLabels는 각 세그먼트의 항목 제목으로 전달됩니다. 라벨을 생략하거나 개수가 부족하면 해당 세그먼트는 아이콘 이름으로 대체됩니다.

case slotView(() -> AnyView)

임의 뷰. slot(_:) 팩토리로 생성합니다.

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

목록에 없는 구성을 직접 배치합니다.

  • Parameters

    ParameterDescription
    content표시할 뷰를 생성하는 클로저

  • Return Value

    구성된 요소

enum Size

텍스트 영역의 사이즈를 정의합니다.

  • Overview

    사이즈에 따라 모서리 반경, 최소 콘텐츠 높이, 입력 타이포그래피, 하단 리소스 크기가 함께 결정됩니다.

Enumeration Cases

case large

큰 사이즈 (입력 body2, 최소 콘텐츠 높이 48)

case medium

중간 사이즈 (입력 label1, 최소 콘텐츠 높이 44)

Relationships

Conforms To

Swift.Sendable

SwiftUICore.View

© 2026 Wanted Lab, Inc.