Text field

일정 높이의 필드 안에 한 줄 이하의 값을 입력할 수 있는 컴포넌트로 Heading, Placeholder, Description 등의 요소를 활용하여 사용자가 입력할 내용의 형식을 보다 명확하게 안내합니다.

@MainActor struct TextField

Overview

이 컴포넌트는 사용자가 텍스트를 입력할 수 있는 필드를 제공합니다. 제목, 아이콘, 자동완성, 상태 표시 등 다양한 기능을 지원합니다.

@State private var inputText = ""

// 기본 텍스트 필드
TextField(text: $inputText)
   .heading("이메일")
   .placeholder("이메일을 입력하세요")

// 아이콘이 있는 필수 입력 필드
TextField(text: $inputText)
   .heading("아이디")
   .requiredBadge(true)
   .icon(.person)
   .status(.negative(description: "올바른 아이디를 입력해주세요"))

// 오른쪽 버튼이 있는 텍스트 필드
TextField(text: $inputText)
   .trailingButton(
       .init(
           variant: .primary,
           title: "인증",
           handler: { verifyCode() }
       )
   )

Topics

Structures

struct AutoCompletionDataSource

텍스트 필드의 자동완성 기능을 위한 데이터 소스를 정의합니다.

Operators

static func == (AutoCompletionDataSource, AutoCompletionDataSource) -> Bool

Initializers

init<V>(numberOfSections: Int, sectionTitleAt: ((Int) -> String)?, numberOfItemsInSection: (Int) -> Int, cellForItemAt: (IndexPath) -> V, headerView: (() -> any View)?, footerView: (() -> any View)?, maxHeight: CGFloat)

자동완성 데이터 소스를 초기화합니다.

  • Parameters
    ParameterDescription
    numberOfSections섹션 수, 생략하면 기본값으로 1 적용
    sectionTitleAt섹션 제목을 반환하는 클로저, 생략하면 기본값으로 nil 적용
    numberOfItemsInSection각 섹션의 항목 수를 반환하는 클로저
    cellForItemAt각 항목의 뷰를 반환하는 클로저
    headerView헤더 뷰 클로저, 생략하면 기본값으로 nil 적용
    footerView푸터 뷰 클로저, 생략하면 기본값으로 nil 적용
    maxHeight자동완성 목록의 최대 높이, 생략하면 기본값으로 400 적용

Instance Properties

var totalNumberOfItems: Int

전체 항목 수를 반환합니다.

struct TrailingButtonInfo

텍스트 필드의 오른쪽에 표시할 버튼의 속성을 정의합니다.

Initializers

init(variant: Button.Color, title: String, handler: (() -> Void)?)

트레일링 버튼을 초기화합니다.

  • Parameters
    ParameterDescription
    variant버튼의 변형 스타일
    title버튼에 표시할 텍스트
    handler버튼 클릭 시 실행할 핸들러

Initializers

init(text: Binding<String>, autoCompletionDataSource: Binding<AutoCompletionDataSource?>)

텍스트 필드를 초기화합니다.

  • Parameters
    ParameterDescription
    text텍스트 필드의 값을 바인딩
    autoCompletionDataSource자동완성 데이터 소스를 바인딩, 생략하면 기본값으로 nil 적용

Instance Properties

var body: some View

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

Instance Methods

func backgroundColor(SwiftUI.Color?) -> TextField

텍스트 필드의 배경색을 설정합니다.

  • Parameters

    ParameterDescription
    color설정할 배경색

  • Return Value

    수정된 텍스트 필드 인스턴스

func disable(Bool) -> TextField

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

  • Parameters

    ParameterDescription
    disable비활성화 여부, true이면 비활성화

  • Return Value

    수정된 텍스트 필드 인스턴스

func heading(String?) -> TextField

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

  • Parameters

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

  • Return Value

    수정된 텍스트 필드 인스턴스

func icon(Icon?) -> TextField

텍스트 필드 왼쪽에 표시할 아이콘을 설정합니다.

  • Parameters

    ParameterDescription
    icon표시할 아이콘

  • Return Value

    수정된 텍스트 필드 인스턴스

func placeholder(String?) -> TextField

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

  • Parameters

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

  • Return Value

    수정된 텍스트 필드 인스턴스

func requiredBadge(Bool) -> TextField

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

  • Parameters

    ParameterDescription
    requiredBadge필수 입력 뱃지 표시 여부

  • Return Value

    수정된 텍스트 필드 인스턴스

  • Discussion

    Note

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

func status(Status) -> TextField

텍스트 필드의 상태를 설정합니다.

  • Parameters

    ParameterDescription
    status텍스트 필드의 상태

  • Return Value

    수정된 텍스트 필드 인스턴스

func trailingButton(TrailingButtonInfo?) -> TextField

텍스트 필드 오른쪽에 표시할 버튼을 설정합니다.

  • Parameters

    ParameterDescription
    trailingButton표시할 버튼의 속성

  • Return Value

    수정된 텍스트 필드 인스턴스

func trailingContent<V>(() -> V) -> TextField

텍스트 필드 오른쪽에 표시할 커스텀 콘텐츠를 설정합니다.

  • Parameters

    ParameterDescription
    trailingContent표시할 커스텀 콘텐츠를 생성하는 클로저

  • Return Value

    수정된 텍스트 필드 인스턴스

Enumerations

enum Status

텍스트 필드의 상태를 정의합니다.

Enumeration Cases

case negative(description: String)

오류 상태, 선택적으로 오류 설명 텍스트 포함 가능

  • Parameters
    ParameterDescription
    description오류 설명 텍스트, 생략하면 기본값으로 "" 적용
case normal(description: String)

기본 상태, 선택적으로 설명 텍스트 포함 가능

  • Parameters
    ParameterDescription
    description설명 텍스트, 생략하면 기본값으로 "" 적용
case positive(description: String)

유효한 입력 상태, 선택적으로 설명 텍스트 포함 가능

  • Parameters
    ParameterDescription
    description설명 텍스트, 생략하면 기본값으로 "" 적용

Relationships

Conforms To

Swift.Sendable

SwiftUICore.View

© 2026 Wanted Lab, Inc.