Warning: This data is provided under the Google User Data Policy. Please review and comply with the policy. Failure to do so might result in project or account suspension.

Sign In With Google HTML API reference

This reference page describes the Sign In With Google HTML data attributes API. You can use the API to display the One Tap prompt or Sign In With Google button on your web pages.

Element with ID "g_id_onload"

You can put Sign In With Google data attributes in any visible or invisible elements, such as <div> and <span>. The only requirement is that the element ID is set to g_id_onload. Do not put this ID on multiple elements.

Data attributes

The following table lists the data attributes with their descriptions:

Attribute
data-client_id Your application's client ID
data-auto_prompt Display Google One tap.
data-auto_select Enables automatic selection on Google One Tap.
data-login_uri The URL of your login endpoint
data-callback The JavaScript ID token handler function name
data-native_login_uri The URL of your password credential handler endpoint
data-native_callback The JavaScript password credential handler function name
data-native_id_param The parameter name for the credential.id value
data-native_password_param The parameter name for the credential.password value
data-cancel_on_tap_outside Controls whether to cancel the prompt if the user clicks outside of the prompt.
data-prompt_parent_id The DOM ID of the One Tap prompt container element
data-skip_prompt_cookie Skips One Tap if the specified cookie has a non-empty value.
data-nonce A random string for ID tokens
data-context The title and words in the One Tap prompt
data-moment_callback The function name of the prompt UI status notification listener
data-state_cookie_domain If you need to call One Tap in the parent domain and its subdomains, pass the parent domain to this attribute so that a single shared cookie is used.
data-ux_mode The Sign In With Google button UX flow
data-allowed_parent_origin The origins that are allowed to embed the intermediate iframe. One Tap will run in the intermediate iframe mode if this attribute presents.
data-intermediate_iframe_close_callback Overrides the default intermediate iframe behavior when users manually close One Tap.

Attribute types

The following sections contain details about each attribute's type and an example.

data-client_id

This attribute is your app's client ID, which is found and created in the Google Developers Console. See the following table for further information:

Type Required Example
string Yes data-client_id="CLIENT_ID.apps.googleusercontent.com"

data-auto_prompt

This attribute determines whether to display One tap or not. The default value is true. Google One tap will not be displayed when this value is false. See the following table for further information:

Type Required Example
boolean Optional data-auto_prompt="true"

data-auto_select

This attribute determines whether or not to return an ID token automatically, without any user interaction, if only one Google session has approved your app. The default value is false. See the following table for further information:

Type Required Example
boolean Optional data-auto_select="true"

data-login_uri

This attribute is the URI of your login endpoint. May be omitted if the current page is your login page, in which case the credential is posted to this page by default.

The ID token credential response is posted to your login endpoint when no callback function is defined and a user clicks on the Sign In With Google or One Tap buttons, or automatic sign takes place.

See the following table for further information:

Type Optional Example
URL Defaults to the URI of the current page, or the value you specify.
Ignored when data-ux_mode="popup" and data-callback is set.
data-login_uri="https://www.example.com/login"

Your login endpoint must handle POST requests containing a credential key with an ID token value in the body.

The following is an example request to your login endpoint:

POST /login HTTP/1.1
Host: www.example.com
Content-Type: application/x-www-form-urlencoded

credential=ID_TOKEN

data-callback

This attribute is the name of the JavaScript function that handles the returned ID token. See the following table for further information:

Type Required Example
string Required if data-login_uri isn't set. data-callback="handleToken"

One of the data-login_uri and data-callback attributes might be used. It depends on the following component and UX mode configurations:

  • The data-login_uri attribute is required for the Sign In With Google button redirect UX mode, which ignores the data-callback attribute.

  • One of these two attributes must be set for Google One Tap and the Google Sign-In button popup UX mode. If both are set, the data-callback attribute has a higher precedence.

data-native_login_uri

This attribute is the URL of your password credential handler endpoint. If you set either the data-native_login_uri attribute or the data-native_callback attribute, the JavaScript library falls back to the native credential manager when there isn't a Google session. You're not allowed to set both the data-native_callback and data-native_login_uri attributes. See the following table for further information:

Type Required Example
string Optional data-login_uri="https://www.example.com/password_login"

data-native_callback

This attribute is the name of the JavaScript function that handles the password credential returned from the browser's native credential manager. If you set either the data-native_login_uri attribute or the data-native_callback attribute, the JavaScript library falls back to the native credential manager when there isn't a Google session. You're not allowed to set both data-native_callback and data-native_login_uri. See the following table for further information:

Type Required Example
string Optional data-native_callback="handlePasswordCredential"

data-native_id_param

When you submit the password credential to the password credential handler endpoint, you can specify the parameter name for the credential.id field. The default name is email. See the following table for further information:

Type Required Example
URL Optional data-native_id_param="user_id"

data-native_password_param

When you submit the password credential to the password credential handler endpoint, you can specify the parameter name for the credential.password value. The default name is password. See the following table for further information:

Type Required Example
URL Optional data-native_password_param="pwd"

data-cancel_on_tap_outside

This attribute sets whether or not to cancel the One Tap request if the user clicks outside of the prompt. The default value is true. To disable it, set the value to false. See the following table for further information:

Type Required Example
boolean Optional data-cancel_on_tap_outside="false"

data-prompt_parent_id

This attribute sets the DOM ID of the container element. If it's not set, the One Tap prompt is displayed at the top-right corner of the window. See the following table for further information:

Type Required Example
string Optional data-prompt_parent_id="parent_id"

This attribute skips One Tap if the specified cookie has a non-empty value. See the following table for further information:

Type Required Example
string Optional data-skip_prompt_cookie="SID"

data-nonce

This attribute is a random string used by the ID token to prevent replay attacks. See the following table for further information:

Type Required Example
string Optional data-nonce="biaqbm70g23"

data-context

This attribute changes the text of the title and messages shown in the One Tap prompt. See the following table for further information:

Type Required Example
string Optional data-context="use"

The following table lists the available contexts and their descriptions:

Context
signin "Sign in with Google"
signup "Sign up with Google"
use "Use with Google"

data-moment_callback

This attribute is the function name of the prompt UI status notification listener. For more information, refer to the data type PromptMomentNotification. See the following table for further information:

Type Required Example
string Optional data-moment_callback="logMomentNotification"

If you need to display One Tap in a parent domain and its subdomains, pass the parent domain to this attribute so that a single shared-state cookie is used. See the following table for further information:

Type Required Example
string Optional data-state_cookie_domain="example.com"

data-ux_mode

This attribute sets the UX flow used by the Sign In With Google button. The default value is popup. This attribute has no impact on the One Tap UX. See the following table for further information:

Type Required Example
string Optional data-ux_mode="redirect"

The following table lists the available UX modes and their descriptions.

UX Mode
popup Performs sign-in UX flow in a pop-up window.
redirect Performs sign-in UX flow by a full page redirection.

data-allowed_parent_origin

The origins that are allowed to embed the intermediate iframe. One Tap will run in the intermediate iframe mode if this attribute presents. See the following table for further information:

Type Required Example
string or string array Optional data-allowed_parent_origin="https://example.com"

The following table lists the supported value types and their descriptions.

Value Types
string A single domain URI. "https://example.com"
string array A list of comma-separated domain URIs. "https://news.example.com,https://local.example.com"

If the value of data-allowed_parent_origin attribute is invalid, the One Tap initialization of the intermediate iframe mode would fail and stop.

Wildcard prefixes are also supported. For example, "https://*.example.com" will match example.com and its subdomains at all levels (e.g news.example.com, login.news.example.com). Things to keep in mind when using wildcards:

  • Pattern strings cannot be composed of only a wildcard and a top level domain. For example https://*.com and https://*.co.uk are invalid; As noted aboved, "https://*.example.com" will match example.com and its subdomains. You can also use a comma separated list to represent 2 different domains. For example, "https://example1.com,https://*.example2.com" will match the domains example1.com, example2.com and subdomains of example2.com
  • Wildcard domains must begin with a secure https:// scheme. "*.example.com" will be considered invalid.

data-intermediate_iframe_close_callback

Overrides the default intermediate iframe behavior when users manually close One Tap by tapping on the 'X' button in the One Tap UI. The default behavior is to remove the intermediate iframe from the DOM immediately.

The data-intermediate_iframe_close_callback field takes effect only in intermediate iframe mode. And it has impact only to the intermediate iframe, instead of the One Tap iframe. The One Tap UI is removed before the callback is invoked.

Type Required Example
function Optional data-intermediate_iframe_close_callback='logBeforeClose'

Element with class "g_id_signin"

If you add g_id_signin to an element's class attribute, the element renders as a Sign In With Google button.

You can render multiple Sign In With Google buttons on the same page. Each button can have its own visual settings. The settings are defined by the following data attributes.

Visual Data attributes

The following table lists visual data attributes and their descriptions:

Attribute
data-type The button type: icon, or standard button.
data-theme The button theme. For example, white or blue.
data-size The button size. For example, small or large.
data-text The button text. For example, "Sign in with Google" or "Sign up with Google".
data-shape The button shape. For example, rectangular or circular.
data-logo_alignment The Google logo alignment: left or center.
data-width The button width, in pixels.
data-locale The button text renders in the language set in this attribute.

Attribute types

The following sections contain details about each attribute's type and an example.

data-type

The button type. The default value is standard. See the following table for further information:

Type Required Example
string Yes data-type="icon"

The following table lists the available button types and their descriptions:

Type
standard A button with text or personalized information:
icon An icon button without text:

data-theme

The button theme. The default value is outline. See the following table for further information:

Type Required Example
string Optional data-theme="filled_blue"

The following table lists the available themes and their descriptions:

Theme
outline The standard button theme:
A standard button with a white background An icon button with a white background A personalized button with a white background
filled_blue The blue-filled button theme:
A standard button with a blue background An icon button with a blue background A personalized button with a blue background
filled_black The black-filled button theme:
A standard button with a black background An icon button with a black background A personalized button with a black background

data-size

The button size. The default value is large. See the following table for further information:

Type Required Example
string Optional data-size="small"

The following table lists the available button sizes and their descriptions.

Size
large A large button:
A large standard button A large icon button A large, personalized button
medium A medium-sized button:
A medium standard button A medium icon button
small A small button:
A small button A small icon button

data-text

The button text. The default value is signin_with. There are no visual differences for the text of icon buttons that have different data-text attributes. The only exception is when the text is read for screen accessibility.

See the following table for further information:

Type Required Example
string Optional data-text="signup_with"

The following table lists the available button texts and their descriptions:

Text
signin_with The button text is “Sign in with Google”:
A standard button labeled 'Sign in with Google' An icon button with no visible text
signup_with The button text is “Sign up with Google”:
A standard button labeled 'Sign up with Google' An icon button with no visible text
continue_with The button text is “Continue with Google”:
A standard button labeled 'Continue with Google' An icon button with no visible text
signup_with The button text is “Sign in”:
A standard button labeled 'Sign in' An icon button with no visible text

data-shape

The button shape. The default value is rectangular. See the following table for further information:

Type Required Example
string Optional data-shape="rectangular"

The following table lists the available button shapes and their descriptions:

Shape
rectangular The rectangular-shaped button. If used for the icon button type, it's the same as square.
A rectangular standard button A rectangular icon button A rectangular personalized button
pill The pill-shaped button. If used for the icon button type, then it's the same as circle.
A pill-shaped standard button A pill-shaped icon button A pill-shaped personalized button
circle The circle-shaped button. If used for the standard button type, then it's the same as pill.
A circular standard button A circular icon button A circular personalized button
square The square-shaped button. If used for the standard button type, then it's the same as rectangular.
A square standard button A square icon button A square personalized button

data-logo_alignment

The alignment of the Google logo. The default value is left. This attribute only applies to the standard button type. See the following table for further information:

Type Required Example
string Optional data-logo_alignment="center"

The following table lists the available alignments and their descriptions:

logo_alignment
left Left-aligns the Google logo:
A standard button with the G logo on the left
center Center-aligns the Google logo:
A standard button with the G logo in the center

data-width

The minimum button width, in pixels. The maximum width available is 400 pixels.

See the following table for further information:

Type Required Example
string Optional data-width=400

data-locale

The pre-set locale of the button text. If it's not set, the browser's default locale or the Google session user’s preference is used. Therefore, different users might see different versions of localized buttons, and possibly with different sizes.

See the following table for further information:

Type Required Example
string Optional data-locale="zh_CN"

Server-side integration

Your server-side endpoints must handle the following HTTP POST requests.

The ID token handler endpoint

The ID token handler endpoint processes the ID token. Based on the status of the corresponding account, you can sign the user in and either direct them to a sign-up page or direct them to an account-linking page for additional information.

The HTTP POST request contains the following information:

Format Name Description
Cookie g_csrf_token A random string that changes with each request to the handler endpoint.
Request parameter g_csrf_token A string that's the same as the previous cookie value, g_csrf_token.
Request parameter credential The ID token that Google issues.
Request parameter select_by How the credential is selected.

The following table lists the possible values for the select_by field. The type of button used along with the session and consent state are used to set the value,

  • The user pressed either the One Tap or Sign In With Google button or used the touchless Automatic sign-in process.

  • An existing session was found, or the user selected and signed-in to a Google Account to establish a new session.

  • Prior to sharing ID token credentials with your app the user either

    • pressed the Confirm button to grant their consent to share credentials, or
    • had previously granted consent and used Select an Account to choose a Google Account.

The value of this field is set to one of these types,

Value Description
auto Automatic sign-in of a user with an existing session who had previously granted consent to share credentials.
user A user with an existing session who had previously granted consent pressed the One Tap 'Continue as' button to share credentials.
user_1tap A user with an existing session pressed the One Tap 'Continue as' button to grant consent and share credentials. Applies only to Chrome v75 and higher.
user_2tap A user without an existing session pressed the One Tap 'Continue as' button to select an account and then pressed the Confirm button in a pop-up window to grant consent and share credentials. Applies to non-Chromium based browsers.
btn A user with an existing session who previously granted consent pressed the Sign In With Google button and selected a Google Account from 'Choose an Account' to share credentials.
btn_confirm A user with an existing session pressed the Sign In With Google button and pressed the Confirm button to grant consent and share credentials.
btn_add_session A user without an existing session who previously granted consent pressed the Sign In With Google button to select a Google Account and share credentials.
btn_confirm_add_session A user without an existing session first pressed the Sign In With Google button to select a Google Account and then pressed the Confirm button to consent and share credentials.

Password credential handler endpoint

The password credential handler endpoint processes password credentials that the native credential manager retrieves.

The HTTP POST request contains the following information:

Format Name Description
Cookie g_csrf_token A random string that changes with each request to the handler endpoint.
Request parameter g_csrf_token A string that's the same as the previous cookie value, g_csrf_token.
Request parameter email This ID token that Google issues.
Request parameter password How the credential is selected.