SmartAddress

A specialized address input component with an integrated smart parsing workflow. It can extract name, phone number, and region fields from pasted text, and supports input, select, and cascader region modes.

Basic Usage (Input Mode)

By default, the region fields are rendered as three plain inputs. Paste address text into the parser area and click "Smart Parse" to fill the form.

Recipient

Phone

Province/City/District

Detailed Address

Basic Usage

Dropdown Select Mode

Set region-type="select" and pass region-options to render linked province, city, and district selects.

Recipient

Phone

Province/City/District

Guangdong

Shenzhen

Nanshan

Detailed Address

Select Mode

Cascader Mode

Set region-type="cascader" to use a cascader picker for region selection.

Recipient

Phone

Province/City/District

Detailed Address

Cascader Mode

Custom Fields and Codes

When backend region data uses custom field names such as name/code/items, configure label-field, value-field, and children-field to map the structure.

Recipient

Phone

Province/City/District

440000

440300

440305

Detailed Address

Custom Fields and Codes

Label Placement

Set label-placement="top" to move labels above the fields.

Recipient

Phone

Province/City/District

Detailed Address

Top Aligned Labels

Usage in Nuxt

YhSmartAddress can be used directly in Nuxt after registering the YH-UI module. The form renders during SSR, and parser or linked region interactions continue on the client after hydration.

Recipient

Phone

Province/City/District

Detailed Address

Usage in Nuxt

How to Configure

Register the module in nuxt.config.ts:

export default defineNuxtConfig({
  modules: ['@yh-ui/nuxt'],
  yhUI: {
    components: ['YhSmartAddress']
  }
})

API

Props

Attribute	Description	Type	Default
model-value / v-model	Current address value	AddressValue	{ name: '', phone: '', province: '', city: '', district: '', street: '', detail: '' }
region-type	Province/city/district mode	'input' | 'select' | 'cascader'	'input'
region-options	Region tree data source	RegionOption[]	[]
label-field	Field name for labels	string	'label'
value-field	Field name for values	string	'value'
children-field	Field name for children	string	'children'
show-name	Whether to display the name field	boolean	true
show-phone	Whether to display the phone field	boolean	true
show-street	Whether to display the street field	boolean	false
show-parser	Whether to display the smart parser	boolean	true
parse-placeholder	Placeholder for the parser input	string	''
parse-button-text	Text for the parse button	string	''
required	Whether fields are required	boolean	false
disabled	Whether to disable the component	boolean	false
label-placement	Label placement	'left' | 'top'	'left'
parser	Custom parser function	(raw: string) => ParsedAddress	null
theme-overrides	Theme variables override	ComponentThemeVars	{}

Events

Event Name	Description	Callback Parameters
update:modelValue	Triggered when value changes	(val: AddressValue) => void
parsed	Triggered after smart parsing	(val: ParsedAddress) => void
change	Triggered when any field changes	(val: AddressValue) => void

Slots

Slot Name	Description
parse-icon	Icon slot on the left side of the parse button
region	Slot for custom region input area
extra	Slot for additional content at the bottom

Expose

This component does not expose public instance methods or properties.

Types

AddressValue

interface AddressValue {
  name: string
  phone: string
  province: string
  city: string
  district: string
  street: string
  detail: string
}

RegionOption

interface RegionOption {
  label?: string
  value?: string | number
  children?: RegionOption[]
  [key: string]: unknown
}

ParsedAddress

interface ParsedAddress {
  name: string
  phone: string
  province: string
  city: string
  district: string
  street: string
  detail: string
}

Theme Variables

YhSmartAddress supports themeOverrides. The following CSS variables are available:

Variable Name	Description	Default Value
--yh-smart-address-parser-bg	Background of smart parse area	var(--yh-color-primary-light-9)
--yh-smart-address-input-bg	Background of input fields	var(--yh-fill-color-blank)
--yh-smart-address-parse-btn-bg	Background of parse button	var(--yh-color-primary)
--yh-smart-address-tip-success	Color of success tip	var(--yh-color-success)
--yh-smart-address-tip-error	Color of error tip	var(--yh-color-danger)
--yh-smart-address-label-width	Width of form labels	72px

Type Exports

Name	Description
YhSmartAddressProps	Component props type
YhSmartAddressEmits	Component emits type
YhSmartAddressSlots	Component slots type
YhAddressValue	Address value type
YhRegionOption	Region option type
YhParsedAddress	Parsed address type
YhSmartAddressInstance	Component instance type