Text area

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

@MainActor struct TextArea

Overview

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

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

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

// 문자 수 제한과 고정 크기를 가진 텍스트 영역
TextArea(text: $longText)
    .resize(.fixed(min: 100, max: 200))
    .bottomResources(
        trailing: [.characterCount(limit: 100)]
    )

// 필수 항목 표시와 설명이 있는 텍스트 영역
TextArea(text: $longText)
    .heading("상세 설명")
    .requiredBadge(true)
    .description("최대한 자세히 작성해주세요")

Topics

Initializers

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

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

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

Instance Properties

var body: some View

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

Instance Methods

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

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

  • Parameters

    ParameterDescription
    leadingResources왼쪽에 표시할 UI 요소 배열 (최대 3개)
    trailingResources오른쪽에 표시할 UI 요소 배열 (최대 3개)
    leadingResourceSpacing왼쪽 요소 간의 간격
    trailingResourceSpacing오른쪽 요소 간의 간격

  • Return Value

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

func description(String?) -> TextArea

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

  • Parameters

    ParameterDescription
    description표시할 설명 텍스트, nil이면 표시 안함

  • Return Value

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

func disable(Bool) -> TextArea

텍스트 영역의 활성화 상태를 설정합니다.

  • Parameters

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

  • Return Value

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

func heading(String?) -> TextArea

텍스트 영역 위에 표시할 제목을 설정합니다.

  • Parameters

    ParameterDescription
    heading표시할 제목, nil이면 제목 표시 안함

  • Return Value

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

func inputCharacterLimit(Int?) -> TextArea

입력 시점에 적용할 최대 글자 수를 설정합니다.

  • Parameters

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

  • Return Value

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

  • Discussion

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

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

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

  • Parameters

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

  • Return Value

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

  • Discussion

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

func negative(Bool) -> TextArea

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

  • Parameters

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

  • Return Value

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

  • Discussion

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

func placeholder(String?) -> TextArea

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

  • Parameters

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

  • Return Value

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

func requiredBadge(Bool) -> TextArea

제목 옆에 필수 입력을 나타내는 뱃지를 표시할지 설정합니다.

  • Parameters

    ParameterDescription
    requiredBadge필수 입력 뱃지 표시 여부, 생략하면 기본값으로 true 적용

  • Return Value

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

  • Discussion

    Note

    제목이 설정되지 않은 경우 뱃지가 표시되지 않습니다.

func resize(Resize) -> TextArea

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

  • Parameters

    ParameterDescription
    resize크기 조절 방식

  • Return Value

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

Enumerations

enum Resize

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

Enumeration Cases

case fixed(min: CGFloat, max: CGFloat)

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

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

최대 8줄까지 표시되며, 초과 부분은 스크롤할 수 있습니다.

case normal

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

enum Resource

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

Enumeration Cases

case badge(ContentBadge.Variant, title: String)

뱃지

  • Parameters
    ParameterDescription
    variant뱃지 변형 스타일, 생략하면 기본값으로 .solid 적용
    title뱃지 텍스트
case characterCount(limit: Int?, overflow: Bool)

문자 수 카운터

  • Parameters
    ParameterDescription
    limit최대 문자 수 제한, 생략하면 기본값으로 nil 적용 (제한 없음)
    overflow최대 문자 수 초과 허용 여부, 생략하면 기본값으로 false 적용
case chip(Chip.Variant, title: String, handler: (() -> Void)?)

칩

  • Parameters
    ParameterDescription
    variant칩 변형 스타일, 생략하면 기본값으로 .solid 적용
    title칩 텍스트
    handler칩 클릭 핸들러, 생략하면 기본값으로 nil 적용
case filterButton(FilterButton.Variant, title: String, handler: (() -> Void)?)

필터 버튼

  • Parameters
    ParameterDescription
    variant버튼 변형 스타일, 생략하면 기본값으로 .solid 적용
    title버튼 텍스트
    handler버튼 클릭 핸들러, 생략하면 기본값으로 nil 적용
case icon(Icon, tintColor: SwiftUI.Color)

단순 아이콘

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

아이콘 버튼

  • Parameters
    ParameterDescription
    placement버튼 위치, 생략하면 기본값으로 .leading 적용
    variant버튼 변형 스타일, 생략하면 기본값으로 .solid(size: .small) 적용
    icon버튼 아이콘
    tintColor아이콘 색상, 생략하면 기본값으로 .semantic(.labelAlternative) 적용
    handler버튼 클릭 핸들러, 생략하면 기본값으로 nil 적용
case textButton(placement: Placement, variant: TextButton.Color?, title: String, handler: (() -> Void)?)

텍스트 버튼

  • Parameters
    ParameterDescription
    placement버튼 위치, 생략하면 기본값으로 .leading 적용
    variant버튼 변형 스타일, 생략하면 기본값으로 .assistive 적용
    title버튼 텍스트
    handler버튼 클릭 핸들러, 생략하면 기본값으로 nil 적용

Enumerations

enum Placement

요소의 배치 위치를 정의합니다.

Enumeration Cases
case leading

왼쪽에 배치

case trailing

오른쪽에 배치

Relationships

Conforms To

Swift.Sendable

SwiftUICore.View

© 2026 Wanted Lab, Inc.