@aws/address-form-sdk-js

中文文档

1.6.1发布于 2026/11/07TypeScriptCommonJS构建来源已验证近 30 天下载 7708

Address Form SDK for Javascript

文档目录15 节

Amazon Location Address Form SDK
Getting Started
Prerequisites
Installation
Use SDK
Customization
Supported Countries
API Reference
AddressForm
Form Input Fields
Form Buttons
AddressForm.Map
Contributing
Security
License

Amazon Location Address Form SDK

The Address Form SDK simplifies the development of autofill address forms. As users type their addresses, the form displays relevant suggestions. Selecting a suggestion populates the subsequent fields, including street, city, state, and postal code. This intelligent feature reduces errors and saves time by eliminating manual typing. Users can preview the selected address on a map and adjust the location pin.

Getting Started

The Address Form SDK can be used within a React app or in a standalone HTML and JavaScript page. Get started by following the instructions below or use the step by step wizard from our console to configure the address form.

Prerequisites

You will need an API key with permission to call the actions listed below. Follow this guide for how to create an API key.

The use of the Address Form will require the following actions to be allowed by your API key:

Action	Purpose	Required When
`GetTile`	Retrieves map tiles for rendering the interactive map	Displaying a map component
`Autocomplete`	Provides real-time address suggestions as users type	Using the Autocomplete API for typeahead functionality
`Suggest`	Provides real-time address suggestions as users type	Using the Suggest API for typeahead functionality
`ReverseGeocode`	Converts coordinates to address	Allowing users to use their current location
`GetPlace`	Retrieves detailed place information for selected addresses	Using the typeahead functionality

Installation

React

Install the SDK in your React app by running: npm install @aws/address-form-sdk-js

HTML/JavaScript

Include the following in your HTML code the CSS and JavaScript for the SDK

...
<head>
  ...
  <link
    rel="stylesheet"
    href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.css"
  />
  ...
</head>
...
<body>
  ...
  <script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.umd.js"></script>
</body>
...

Use SDK

Implement the following code into your React app. Replace the AMAZON_LOCATION_API_KEY value with your API key and AMAZON_LOCATION_REGION with the region of the API key.

React

import React from "react";
import { AddressForm, Flex } from "@aws/address-form-sdk-js";

export default function App() {
  return (
    <AddressForm
      apiKey="AMAZON_LOCATION_API_KEY"
      region="AMAZON_LOCATION_REGION"
      onSubmit={async (getData) => {
        // Get form data with intendedUse parameter
        // Use "SingleUse" for one-time display only
        // Use "Storage" if you plan to store/cache the results - makes an extra API call to grant storage rights
        const data = await getData({ intendedUse: "SingleUse" });
        console.log(data);
      }}
    >
      <Flex direction="row" flex>
        <Flex direction="column">
          <input
            data-api-name="autocomplete"
            data-type="address-form"
            name="addressLineOne"
            placeholder="Enter address"
          />
          <input data-type="address-form" name="addressLineTwo" />
          <input data-type="address-form" name="city" placeholder="City" />
          <input data-type="address-form" name="province" placeholder="State/Province" />
          <input data-type="address-form" name="postalCode" />
          <input data-type="address-form" name="country" placeholder="Country" />
          <Flex direction="row">
            <button data-type="address-form" type="submit">
              Submit
            </button>
            <button data-type="address-form" type="reset">
              Reset
            </button>
          </Flex>
        </Flex>
        <AddressForm.Map mapStyle={["Standard", "Light"]} />
      </Flex>
    </AddressForm>
  );
}

HTML/JavaScript

<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Address Form</title>
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.css"
    />
  </head>
  <body>
    <form id="amazon-location-address-form" class="aws-address-form aws-flex-row aws-flex-1">
      <div class="aws-flex-column">
        <input
          data-type="address-form"
          name="addressLineOne"
          data-api-name="suggest"
          data-show-current-location="true"
        />
        <input data-type="address-form" name="addressLineTwo" />
        <input data-type="address-form" name="city" />
        <input data-type="address-form" name="province" />
        <input data-type="address-form" name="postalCode" />
        <input data-type="address-form" name="country" />
        <div class="aws-flex-row">
          <button data-type="address-form" type="submit">Submit</button>
          <button data-type="address-form" type="reset">Reset</button>
        </div>
      </div>
      <div data-type="address-form" data-map-style="Standard,Light"></div>
    </form>
    <script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.umd.js"></script>
    <script>
      AddressFormSDK.render({
        root: "#amazon-location-address-form",
        apiKey: "AMAZON_LOCATION_API_KEY",
        region: "AMAZON_LOCATION_REGION",
        showCurrentCountryResultsOnly: true,
        onSubmit: async (getData) => {
          // Get form data with intendedUse parameter
          // Use "SingleUse" for one-time display only
          // Use "Storage" if you plan to store/cache the results - makes an extra API call to grant storage rights
          const data = await getData({ intendedUse: "SingleUse" });
          console.log(data);
        },
      });
    </script>
  </body>
</html>

Customization

The form is fully customizable - add, remove, or rearrange elements as needed for your use case. Replace the Flex component with your own CSS framework or custom styling. You can control other functionalities of the address form through the component props/attributes. See the API Reference for complete customization options.

Supported Countries

The Address Form SDK supports address autofill worldwide through Amazon Location Service. The following countries have full support with address field parsing, where each address component is populated into its respective field:

Australia
Canada
France
Hong Kong
Ireland
New Zealand
Philippines
Singapore
United Kingdom
United States

Other countries are in Preview, where the addressLineOne field displays the complete address instead of just the street address portion. Future releases will improve this behavior.

API Reference

AddressForm

React: The main component that wraps the address form functionality. <AddressForm>

HTML/JavaScript: The function used for rendering the address form onto the page AddressForm.render({ ... })

Props

Property	Type	Required	Default	Description
`apiKey`	`string`	Yes	-	The Amazon Location Service API key used to authenticate requests.
`region`	`string`	Yes	-	The AWS region where Amazon Location Service is called (e.g., "us-east-1")
`language`	`string`	No	-	Language code for localized address suggestions (e.g., "en", "es")
`politicalView`	`string`	No	-	Political view for address results, affecting disputed territories display
`showCurrentCountryResultsOnly`	`boolean`	No	`false`	Limits autofill suggestions to the country selected in the `Country` field
`allowedCountries`	`string[]`	No	-	Array of ISO country codes (alpha-2 or alpha-3) to restrict address suggestions. See countries.ts for alpha-2 reference
`placeTypes`	`AutocompleteFilterPlaceType[]`	No	-	Array of place types to filter results (e.g., "Locality", "PostalCode")
`initialMapCenter`	`[number, number]`	No	-	Initial map center as [longitude, latitude] coordinates. If not provided and a single country is specified in `allowedCountries`, the map centers on that country's capital
`initialMapZoom`	`number`	No	Varies	Initial map zoom level. Defaults: 10 when `initialMapCenter` is provided, 5 when centering on a single allowed country, 1 otherwise
`centerBounds`	`[[number, number], [number, number]]`	No	-	Supported-region box as `[[west, south], [east, north]]` in [longitude, latitude]. When set, search stays in-region (the typeahead bias is clamped into the box, so results stay in-region even if the user pans the map away); clicking the current-location button from a device outside the box shows a warning and leaves the field untouched, rather than returning the nearest in-region address; and the adjustable pin is kept in-region: if the user drags the pin outside the box, the map's adjustment bar shows an out-of-region warning, its "Undo adjustment" action returns the pin, and form submission is blocked until it is back in the region. Use for data providers that only cover part of the world (e.g. GrabMaps in Southeast Asia).
`onSubmit`	`(getData) => void`	No	-	Callback function that receives a `getData` async function for retrieving form data with intendedUse parameter

Form Submission Data

When the form is submitted, the onSubmit callback receives a getData async function. Call this function with an intendedUse parameter to retrieve the form data:

onSubmit: async (getData) => {
  const data = await getData({
    intendedUse: "SingleUse", // or "Storage"
  });
};

Important: Use "Storage" if you plan to store or cache the results. This ensures compliance with Amazon Location Service intended use requirements.

The returned data object contains the following properties:

Property	Type	Description
`placeId`	`string`	Place ID from Amazon Location Service (only present when address was selected from typeahead or locate button)
`addressLineOne`	`string`	Primary address line (street address)
`addressLineTwo`	`string`	Secondary address line (apartment, suite, etc.)
`city`	`string`	City name
`province`	`string`	State or province
`postalCode`	`string`	Postal or ZIP code
`country`	`string`	Country code (ISO 3166-1 alpha-2)
`originalPosition`	`string`	Original coordinates from API response (longitude,latitude)
`adjustedPosition`	`string`	User-adjusted coordinates if map pin was moved (longitude,latitude)
`addressDetails`	`Address`	Complete address object from Amazon Location Service API (GetPlace/ReverseGeocode response)

Note: The addressDetails property contains the full API response from Amazon Location Service and is only present when the address was populated through our APIs (typeahead selection or locate button). Addresses entered manually by users will not contain this property.

Form Input Fields

All input fields use the data-type="address-form" attribute along with a name= attribute. The following common properties are supported:

Common Input Properties

Property	Type	Required	Description
`label`	`string`	No	Custom label for the input field
`placeholder`	`string`	No	Placeholder text for the input
`className`	`string`	No	CSS class names for custom styling

Address Line One (`name="addressLineOne"`)

Primary address input with autofill functionality. See Supported Countries for information about address field parsing behavior in different countries.

Property	Type	Default	Description
`label`	`string`	"Address"	Label for the field
`placeholder`	`string`	"Enter address"	Placeholder text
`data-api-name`	`string`	"suggest"	API type: `autocomplete` or `suggest`. Use `suggest` to return both POI and address suggestions, and `autocomplete` to return address-only suggestions
`data-show-current-location`	`string`	"true"	Enables current location functionality using the browser’s Geolocation API. This will prompt the user for permission to access their location

Other Input Fields

Address Line Two (name="addressLineTwo"): Default label "Address Line 2", placeholder "Apartment, suite, etc."
City (name="city"): Default label "City"
Province/State (name="province"): Default label "Province/State"
Postal Code (name="postalCode"): Default label "Postal/Zip code"
Country (name="country"): Default label "Country"

Form Buttons

Submit Button

<button data-type="address-form" type="submit">Submit</button>

Reset Button

<button data-type="address-form" type="reset">Reset</button>

AddressForm.Map

Map component for displaying and adjusting address location.

React: Map component for displaying and adjusting address location. <AddressForm.Map mapStyle={...}>

HTML/JavaScript: Map element for displaying and adjusting address location.<div data-type="address-form" data-map-style="...">

Props

React Property	React Type	HTML/JavaScript Attribute	HTML/JavaScript Type	Required	Default	Description
`mapStyle`	`array`	`data-map-style`	`string`	Yes	-	Map style configuration
`showNavigationControl`	`boolean`	`data-show-navigation-control`	`string`	No	`true`	Display map navigation controls
`adjustablePosition`	`boolean`	`data-adjustable-position`	`string`	No	`true`	Allow users to adjust address position

Map Style Options

Map styles consist of two parts: the map style name and the color scheme. The map style name determines the visual theme (Standard, Monochrome, Hybrid, or Satellite), while the color scheme specifies the brightness variant (Light or Dark) where applicable.

React Implementation (Array Format)	HTML/JavaScript Implementation (String Format)
`['Standard', 'Light']`	`"Standard,Light"`
`['Standard', 'Dark']`	`"Standard,Dark"`
`['Monochrome', 'Light']`	`"Monochrome,Light"`
`['Monochrome', 'Dark']`	`"Monochrome,Dark"`
`['Hybrid']`	`"Hybrid"`
`['Satellite']`	`"Satellite"`

For detailed descriptions of each map style and color scheme, see AWS map styles and customization.

Contributing

We welcome community contributions and pull requests. See CONTRIBUTING for information on how to set up a development environment, and submit code.

Security

See CONTRIBUTING for more information.

License

This project is licensed under the Apache-2.0 License.

版本与发布记录

@aws/address-form-sdk-js 共发布 10 个版本，首次发布于 2025/11/04；过去 12 个月发布了 9 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本	发布日期	距今
`1.6.1`latest	2026/11/07	1 天前
`1.6.0`	2026/08/12	2 个月前
`1.5.0`	2026/07/14	3 个月前
`1.4.1`	2026/03/11	7 个月前
`1.4.0`	2026/01/31	9 个月前
`1.3.0`	2025/12/31	10 个月前

关于 @aws/address-form-sdk-js 的常见问题

@aws/address-form-sdk-js 是什么？

Address Form SDK for Javascript

如何安装 @aws/address-form-sdk-js？

在项目目录运行 npm install @aws/address-form-sdk-js，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^19.0.0）、react-dom（^19.0.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

@aws/address-form-sdk-js 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@aws/address-form-sdk-js 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require()；在 ES Module 项目中也可以用 import 引入（Node.js 会把 module.exports 作为默认导出）。

@aws/address-form-sdk-js 可以商用吗？

@aws/address-form-sdk-js 使用未声明许可。package.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

@aws/address-form-sdk-js 的下载量有多少？

根据 npm 官方下载统计，@aws/address-form-sdk-js 在 2026/10/08 – 2026/11/06 这 30 天内被下载 7,708 次，日均约 257 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@aws/address-form-sdk-js 还在维护吗？

最新版本 1.6.1 发布于 2026/11/07（1 天前）；至今共发布 10 个版本，其中过去 12 个月发布了 9 个；首次发布于 2025/11/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @aws/address-form-sdk-js

pnpmpnpm add @aws/address-form-sdk-js
yarnyarn add @aws/address-form-sdk-js
bunbun add @aws/address-form-sdk-js

peer 依赖react ^19.0.0react-dom ^19.0.0

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

在你的项目目录中运行此命令。

近 30 天下载

7,708

约 7708 次日均 257 次

统计周期 2026/10/08 – 2026/11/06
数据来自 npm 官方下载统计，今天更新

最新版本1.6.1发布于 1 天前

开源许可未声明未声明

包体积2.6 MB61 个文件 · 解压后

运行依赖10 个另有 2 个 peer 依赖

模块格式CommonJS

TypeScript自带类型

发布版本10 个近 12 个月 9 个

首次发布2025/11/041 年前

元数据更新2026/11/07

每一个软件包背后，
都有分享与创造的人。

@aws/address-form-sdk-js

Amazon Location Address Form SDK

Getting Started

Prerequisites

Installation

React

HTML/JavaScript

Use SDK

React

HTML/JavaScript

Customization

Supported Countries

API Reference

AddressForm

Props

Form Submission Data

Form Input Fields

Common Input Properties

Address Line One (name="addressLineOne")

Other Input Fields

Form Buttons

Submit Button

Reset Button

AddressForm.Map

Props

Map Style Options

Contributing

Security

License

版本与发布记录

关于 @aws/address-form-sdk-js 的常见问题

@aws/address-form-sdk-js 是什么？

如何安装 @aws/address-form-sdk-js？

@aws/address-form-sdk-js 支持 TypeScript 吗？

@aws/address-form-sdk-js 支持 ESM 还是 CommonJS？

@aws/address-form-sdk-js 可以商用吗？

@aws/address-form-sdk-js 的下载量有多少？

@aws/address-form-sdk-js 还在维护吗？

Address Line One (`name="addressLineOne"`)