Documentation
Feedback
Guides

Login

The VTEX Login app is responsible for handling user login in your store.

{"base64":"  ","img":{"width":2857,"height":1497,"type":"gif","mime":"image/gif","wUnits":"px","hUnits":"px","length":840962,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-login-0.gif"}}

Configuration

  1. Add the Login app to your theme's dependencies in the manifest.json file:

_10
"dependencies": {
_10
+ "vtex.login": "2.x"
_10
}

Now, you are able to use all the blocks exported by the Login app. Check out the full list below:

Block nameDescription
login
{"base64":"  ","img":{"width":69,"height":20,"type":"svg","mime":"image/svg+xml","wUnits":"px","hUnits":"px","length":923,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-login-1.png"}}
Renders the Login component, as shown in the media above.
login-contentOnly renders the login form .
  1. Add the login block and its props to your store's header. For example:

_10
"login": {
_10
"props": {
_10
"emailAndPasswordTitle": "LOG-IN",
_10
"accessCodeTitle": "Acess Code LOG-IN",
_10
"emailPlaceholder": "e-mail",
_10
"passwordPlaceholder": "password",
_10
"showPasswordVerificationIntoTooltip": true,
_10
}
_10
}

login props

Prop nameTypeDescriptionDefault value
optionsTitlestringText to entitle the login options.undefined
emailAndPasswordTitlestringText to display the email-and-password option.undefined
accessCodeTitlestringText to display the access-code option.undefined
emailPlaceholderstringText to be displayed as placeholder to the email input.undefined
passwordPlaceholderstringText to be displayed as placeholder to the password input.undefined
acessCodePlaceholderstringText to be displayed as placeholder to the access code input.undefined
showPasswordVerificationIntoTooltipbooleanWhether a tooltip responsible for checking the password format should be shown (true) or not (false).true
showIconProfilebooleanWhether the hpa-profile icon from Store Icons should be displayed on the Login component (true) or not (false).true
iconLabelstringText string to entitle the Login icon.undefined
hideIconLabelbooleanWhether the text string defined for the Login icon should be hidden (true) or not (false).false
labelClasses[string]Login icon's classnames.undefined
providerPasswordButtonLabelstringText to be displayed as the password button label.undefined
identifierPlaceholderstringText to be displayed as placeholder to the extension input.undefined
invalidIdentifierErrorstringError message for invalid user identifier.undefined
mirrorTooltipToRightbooleanWhether the Login tooltip should open towards the right side of the screen (true) or not (false).false
logInButtonBehaviorenumExpected behavior of the Login component when clicked on. Possible values are: popover (opens a popover tab) and link (redirects user to the /login page).popover
accountOptionsButtonBehaviorenumExpected behavior of the My account button when clicked on. Possible values are: popover (opens a popover tab) and link (redirects user to the /account page).popover
accountOptionLinks[object]Creates a custom link to replace the default one set for the accountOptionsButtonBehavior's link value (/account). Check out below the available props for the object.undefined
termsAndConditionsstringText to be displayed below the login options regarding terms&conditions.undefined
hasGoogleOneTapboolean
{"base64":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAQAAAACCAIAAADwyuo0AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAI0lEQVR4nGO4Ge70f82ED0Uxi2QFGdwYGOabqq1zNAhiYAAAkfgI7Rdimv8AAAAASUVORK5CYII=","img":{"src":"https://img.shields.io/badge/-Beta-red","width":35,"height":20,"type":"svg"}}
Whether the Google's One-tap sign-up and auto sign-in.
false
googleOneTapAlignmentenum
{"base64":"  ","img":{"width":35,"height":20,"type":"svg","mime":"image/svg+xml","wUnits":"px","hUnits":"px","length":903,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-login-3.png"}}
Defines pop-up alignment for the Google One-tap login. Possible values are Left and Right.
Right
googleOneTapMarginTopstring
{"base64":"  ","img":{"width":35,"height":20,"type":"svg","mime":"image/svg+xml","wUnits":"px","hUnits":"px","length":903,"url":"https://cdn.jsdelivr.net/gh/vtexdocs/dev-portal-content@main/images/vtex-login-4.png"}}
Defines the pop-up top margin for the Google One-tap login. The values supported are the same supported by the CSS property top.
3rem
disabledEmailInputsbooleanWhether user email editing should be allowed (true) or not (false).false
blockOAuthAutoRedirectbooleanIf this prop is true and the only active provider is an OAuth, the login won't auto-redirect as usual. Also, the query string oAuthRedirect will be disabled.false

Notice that the Google One Tap props are still in Beta. Although they are ready to be used, UX improvements should be expected.

  • accountOptionLinks object:
Prop nameTypeDescriptionDefault value
labelstringText lable for the custom link.undefined
pathstringCustom link's path.undefined
cssClass[string]Login icon's class names.undefined

login-content props

Prop nameTypeDescriptionDefault value
isInitialScreenOptionOnlybooleanWhether only the login options will be displayed on the initial screen (true) or not (false).true
defaultOptionenumDefines the default login options to be shown. Possible values are: 0 (shows the access-code option for login), 1 (shows the email/password option for login) and 2 (shows the corporate option for login).0
optionsTitlestringText to entitle the login options.undefined
emailAndPasswordTitleStringText to display the email-and-password option.undefined
accessCodeTitlestringText to display the access-code option.undefined
emailPlaceholderstringText to be displayed as placeholder to the email input.undefined
passwordPlaceholderstringText to be displayed as placeholder to the password input.undefined
showPasswordVerificationIntoTooltipbooleanWhether a tooltip responsible for checking the password format should be shown (true) or not (false).true
acessCodePlaceholderstringText to be displayed as placeholder to the access code input.undefined
providerPasswordButtonLabelstringText to be displayed as the password button label.undefined
identifierPlaceholderstringText to be displayed as placeholder to the extension input.undefined
invalidIdentifierErrorstringError message for invalid user identifier.undefined
termsAndConditionsstringText to be displayed below the login options regarding terms&conditions.undefined
disabledEmailInputsbooleanWhether user email editing should be allowed (true) or not (false).false

Advanced configuration

The email/password login asks by default two inputs from users:

  • The email (user identifier)
  • The password

It is possible to set up the User Identifier Extension, allowing other identifiers to be used in the Login's form instead - as long as they can be resolved to the user email behind the scenes.

For example: if your account stores the National Identity Document of each user, the email/password login could be changed to ask for the following two inputs:

  • The National Identity Document (user identifier)
  • The password

In order to display an identifier other than the user email, you must create an extension app of your own to work behind the scenes with the Login component.

The new extension app should be set up to receive the custom user identifier from the interface, such as the National Identity Document, and link it to the accurate user using the store data. Thereafter, the app should fetch the user email and return it to the Login app, which will behave as if the user just typed in their email.

Find below the needed instructions to perform the User Identifier Extension in your store:

This extension is only allowed for enterprise clients. You can check your account plan in your VTEX contract.

  1. Ensure that the Login app is added as your extension app's dependency and that the store builder is listed as one of its builders, as shown below:

_10
"dependencies": {
_10
"vtex.login": "2.x"
_10
},


_10
"builders": {
_10
"store": "0.x",
_10
},

  1. Develop a new component to replace the email input in the login form. It can be anything you desire for that position, such as a file uploader or a simple text input which takes the National Identity Document.

When developing it, remember that it must know how to convert the custom identifier to an email. This should be done by registering a callback function, which returns an email within the Login app, in the react/{{ComponentName}}.js file. For example:


_44
import { useState, useCallback, useEffect } from "react";
_44
_44
const ComponentName = ({
_44
renderInput,
_44
identifierPlaceholder,
_44
registerSubmitter,
_44
}) => {
_44
// The component receives 3 props:
_44
// - renderInput is a function that returns the same Input component used by the login app, defined in styleguide.
_44
// It receives an object with three named parameters, trivially used by Inputs with react: value, onChange, placeholder.
_44
// When "onChange" is called, the login app clears the "email is invalid" error, if it exists.
_44
// - identifierPlaceholder is the value of the configuration "identifierPlaceholder" defined in the Store Front. It has a
_44
// fallback to the value of the configuration "emailPlaceholder".
_44
// - registerSubmitter is a function that receives your async callback function defined in this file. Your callback will be called
_44
// when the user submits the form.
_44
_44
// This code controls the state of the rendered Input component.
_44
const [inputValue, setInputValue] = useState("");
_44
const onChangeInput = useCallback(
_44
(e) => setInputValue(e.target.value),
_44
[setInputValue]
_44
);
_44
_44
// This callback function (onSubmit) should return the resolved email. In the example below, it adds `@email.com` to the current
_44
// value in the Input component (eg. "john" would be resolved to "john@email.com").
_44
const onSubmit = useCallback(async () => {
_44
const email = `$\{inputValue\}@email.com`;
_44
return email;
_44
}, [inputValue]);
_44
_44
// This code registers the async callback function you defined in the login app when this component mounts.
_44
useEffect(() => {
_44
registerSubmitter(onSubmit);
_44
}, [registerSubmitter, onSubmit]);
_44
_44
// The component calls "renderInput" and renders its result.
_44
return renderInput({
_44
value: inputValue,
_44
onChange: onChangeInput,
_44
placeholder: identifierPlaceholder,
_44
});
_44
};
_44
_44
export default ComponentName;

  1. In the store/interfaces.json file, create a new interface for user-identifier, declaring the component you created in the previous step:

_10
"user-identifier.{{InterfaceName}}": {
_10
"component": "{{ComponentName}}"
_10
},

The interface name, which is represented in the example above as {{InterfaceName}}, can be any of your choosing. ℹ️ In the example above, the component created in the step 2 is represented by {{ComponentName}}.

  1. In the store/plugins.json file, plug in the new interface (user-identifier) to the Login app:

_10
"login > user-identifier": "user-identifier.{{InterfaceName}}",
_10
"login-content > user-identifier": "user-identifier.{{InterfaceName}}",

If the store/plugins.json file is not available, you should create it.

Since the Login app behaves as if users were typing their emails, error messages like The email is invalid may appear even if the component is asking users other identifiers. This message, along with others, can be edited in the admin's CMS.

Modus Operandi

The Login app reads the following query-string parameters:

  • returnUrl - Redirects users to the given returnUrl once they are logged in. Caution: This parameter only works for the store's domain and should be UTF-8 encoded (as in javascript's encodeURIComponent).
  • oAuthRedirect - Redirects users to the given OAuth Provider page, instead of displaying the native login options. For this to work, the given OAuth Provider must be listed on the component as one of the login options. Caution: The parameter value is case sensitive and must be Google, Facebook or the registered name of the chosen OAuth Provider.
  • userEmail - User email data.
  • flowState - Default state of the login flow. Possible values:
    • createPass - Sends an email to users with the code required to create a new password. Caution: When used, this parameter also requires the userEmail query string in the same URL.

Use the parameters above to build the Login's desired URLs - through which you will be able to set the expected behavior for the component.

Customization

In order to apply CSS customizations in this and other blocks, follow the instructions given in the recipe on Using CSS Handles for store customization.

CSS Handles
container
contentInitialScreen
contentFormVisible
profile
label
optionsSticky
optionsList
optionsListItem
optionsListItemContainer
accessCodeOptionBtn
emailPasswordOptionBtn
corporateOptionBtn
facebookOptionBtn
googleOptionBtn
customOAuthOptionBtn
oauthProvider
inputContainer
inputContainerAccessCode
inputContainerPassword
inputContainerEmail
emailVerification
emailForm
emailAndPasswordForm
forgotPasswordForm
formLinkContainer
arrowUp
buttonLink
formError
content
content--emailVerification
content--emailAndPassword
content--codeConfirmation
content--accountOptions
content--recoveryPassword
button
sendButton
buttonSocial
buttonDanger
backButton
accountOptions
codeConfirmation
corporateEmail
formTitle
formSubtitle
box
contentContainer
formFooter
contentForm
contentAlwaysWithOptions
options
tooltipContainer
tooltipContainerTop
tooltipContainerLeft
loginOptionsContainer
termsAndConditions
forgotPasswordLink
dontHaveAccount
eyeIcon
Contributors
1
Photo of the contributor
+ 1 contributors
Was this helpful?
Yes
No
Suggest Edits (GitHub)
Contributors
1
Photo of the contributor
+ 1 contributors
On this page