Docs
Inputs

Address Field

An address field whose suggestions pour out as a glass list and resolve into a structured address with street, city and coordinate.

$npx swiftpieces add AddressField
Try it in the Playground Use it on a real screen, take it apart, remix it, and copy the SwiftUI. No account needed.
Free · MIT + Commons ClauseiOS 17.0+Liquid Glassaddressautocompletemapkitcheckoutdeliveryformsearch
Type
AddressField
Files
AddressField.swift
Depends on
Nothing (Apple frameworks only)
Version
1.2.0

Address entry with type-ahead suggestions that resolve to a structured, verified address. The field is a liquid glass shape, and what it shows buds out of it: the suggestion list pours down out of the field and rests apart from it, the clear (or searching) bubble comes out of its end, and the bubble that spins while a pick resolves comes out of the list beside the chosen row. Each melts back into where it came from. Typing searches after a short pause (three characters or more). Each new keystroke cancels the search in flight, so a slow answer for an older query never replaces a newer one. Picking a suggestion looks up the full address; when it arrives, address is set, text becomes the address's first line (usually the street) and the locality shows under it. Editing the text again clears address. Location permission is never requested: suggestions come from the query alone, optionally biased by region. swift @State private var query = "" @State private var address: AddressField.Address? AddressField("Delivery address", text: $query, address: $address, countries: ["US", "CA"])

Notes

  • The field is a liquid glass shape (Liquid Glass on iOS 26, a frosted fallback before it, a solid fill under Reduce Transparency), and what it shows buds out of it and melts back in. The suggestion list pours down out of the field and rests apart from it, 26pt below. A round bubble as tall as the field buds from the field's end while you edit: it spins while suggestions load and is a clear button otherwise. While that bubble is out the field gives it its end, and the list follows the field's edge, so the two stay in line with the bubble's column beside them. Style.field tints the glass; .clear, the default, leaves it neutral.
  • Typing searches once the trimmed text is three characters or more, after a 250ms pause. The search runs in a task keyed on the text, so every keystroke cancels the one in flight: a slow answer for an older query can never replace a newer list. Earlier suggestions stay on screen while the next ones load, with the field's bubble spinning instead of a flicker.
  • Suggestions come from MKLocalSearchCompleter with resultTypes = .address, at most five, with the matched runs in the label colour, the rest of the title in the secondary colour, and the locality on a second line. Picking one runs an MKLocalSearch for that completion: the other rows dim and a spinner bubble buds out of the list's end beside the chosen row. Picking another row, editing the text or leaving the screen cancels the lookup, and a late answer is ignored.
  • Once resolved, address holds the street, city, state, postal code, country, ISO country code, coordinate and a single line formatted for the address's own country. text becomes the first line (usually the street), the rest shows under it in the field and a sage check lands inside the field. mailingLines gives the label lines in the country's postal order.
  • Editing the text clears address. Setting address from outside (a saved address) fills the field without searching, and its check lands on a short spring with no success pop or haptic; setting text and address together is not treated as an edit.
  • A failed lookup stays on its row: the row's pin turns into a butter warning mark, the message replaces the locality, and the spinner bubble beside it turns butter with a retry arrow; tapping the bubble or the row tries again. A failed suggestion request shows "Couldn't load suggestions" with the same butter retry bubble beside it. No matches is a quiet line. In each of these cases a "Use as typed" row sets an address with isVerified == false holding only the typed text. Turn it off with allowsUnverified: false.
  • countries: ["US", "CA"] leaves out suggestions whose last line names another country, and a picked address outside the list shows "Choose an address in United States" on its row instead of being set, with no retry bubble since trying again gives the same answer. region biases suggestions toward an area. Location permission is never requested.
  • iOS 26 moves map items to MKAddress, which has no separate street or postal code, and deprecates MKPlacemark. On iOS 17 to 25 the parts come from the placemark; on iOS 26 from the item's placemark read dynamically (so the file builds without deprecation warnings), with MKAddressRepresentations for the formatted line, city and country as the fallback.
  • source: swaps MapKit for your own backend, or a fixed list for previews and tests. Both calls are cancelled when their result is no longer wanted.
  • Hardware keyboard: up and down arrows move the highlight, Return picks the highlighted row (or the top one), Escape closes the list. A long street wraps up to three lines. A pasted multi-line address is joined with commas.
  • The list sits inline under the field and pushes content down, so it scrolls with a form and never clips inside a scroll view. Leaving the field hides it; coming back shows it again.
  • Motion: the list is born as a thin sliver tucked inside the field's bottom edge and springs down to its place, growing to full height as the neck between them stretches and snaps; its room in the layout opens with it, so what sits below glides down. Going home it reaches back up, melts into the field on a spring with no bounce, and only then leaves the layout, its rows gone the moment it heads back. As it refines while you type it resizes without overshoot, so nothing below it wobbles, and typing itself is never animated or delayed. Bubbles bud out of their parent's end on the same cycle, their glyphs blurring in just after they leave and out the moment they head home, and a glyph that changes inside a bubble (spinner to clear, spinner to retry) blurs from one to the other. A row's highlight wash is there on touch-down, the row sinks about a point, and the wash fades as the finger lifts; bubbles sink too and spring back. When a pick resolves, the spinner and the list melt home as the street and locality settle into the field, which grows for the second line with a little give, and the sage check lands on the expressive spring as the success haptic plays.
  • Type is one weight, semibold, for the text, rows and every glyph; size and colour set the hierarchy.
  • VoiceOver: the field's hint says whether the address is verified; the suggestion count ("5 suggestions", inflected), "Finding address", the result and any error are announced; rows are buttons read as title and locality with the selected trait when highlighted. The clear bubble is "Clear address"; a failed suggestion request's bubble is "Retry suggestions".
  • Haptics: a soft impact on picking a suggestion, success when the address resolves, error when a lookup fails, selection ticks for arrow-key moves. "Use as typed" sets the address at once, so it plays only the success. Nothing per keystroke.
  • Dynamic Type: rows and the field grow and wrap; at accessibility sizes the leading glyphs step aside so titles get the width.
  • Style sets the field tint, label, secondary label, focus ring, row highlight, success, error (the warning mark and the retry bubble) and ink colors, the pin, optional suggestion tiles, the corner radius and the minimum height (also the bubbles' size).
  • Reduce Motion: the list and bubbles fade in and out in place instead of budding, glyph changes fade, and pressed rows and buttons dim instead of sinking. Highlights, the dimmed rows during a lookup, the spinners, colors, announcements and haptics are unchanged. Reduce Transparency draws the field, list and bubbles as solid shapes.

Usage

AddressFieldExample()

Parameters

ParameterDescription
labelThe placeholder shown while the field is empty, and its accessibility label.
textBound text. Set by typing, and to the address's first line once a suggestion resolves.
addressThe resolved address, or nil while there is none. Setting it from outside (a saved address) fills the field and skips searching. Editing the text sets it back to nil.
regionBiases suggestions toward an area, such as the city a store delivers in. nil searches everywhere, starting with the device's region.
sourceWhere suggestions and addresses come from. nil (the default) uses MapKit. Pass your own for a geocoding backend, previews or tests.
countriesISO 3166 country codes that are accepted, such as ["US", "CA"]. Suggestions clearly in another country are left out, and a picked address outside the list shows an inline error instead of being set. Empty accepts every country.
allowsUnverifiedWhen true, a "Use as typed" row appears when there are no matches or a lookup fails, and picking it sets an address with isVerified == false holding only the typed text.
styleColors and field metrics. Defaults to the SwiftPieces house palette, adapting to light and dark.

Install

Pick one. Run it from the folder that contains your .xcodeproj and the files land inside your app.

Terminal

$npx swiftpieces add AddressField

Or ask your coding agent · Claude Code, Cursor or Xcode, once the MCP server is connected

>Add the SwiftPieces "Address Field" piece to my app

Or copy the source above into your app.

New to SwiftUI?If you know React, CSS or Tailwind, SwiftUI is easier to pick up than it looks.Try real app patterns first

Building a whole app? See SwiftPieces Pro →

All inputs and forms →

Build it yourself: SwiftUI haptics guide

On this page

SwiftPiecesPro

Build the whole app with one library.

Production-ready screens, whole flows, complete app templates, a Build Kit your agent follows and Pro remixing.

Explore Pro