This page is about version 2.37.1 of the app, which is not the most recent version. The latest stable version is 2.59.0.

The VTEX Login app responsible to handle user login, and this app is used by store theme.

:loudspeaker: Disclaimer: Don't fork this project; use, contribute, or open issue with your feature request.

Release	Status	Initial Release	Maintenance LTS Start	End-of-life	Store Compatibility
[2.x]	Current Release	2018-11-08			2.x
[1.x]	Maintenance LTS	2018-07-26	2018-11-08	March 2019	1.x

See our LTS policy for more information.

• Features
  • Query Parameters
• Usage
  • Blocks API
    • Configuration
  • Plugins API
    • User Identifier Extension
      • Creating the User Identifier Extension App
  • Styles API
    • CSS namespaces
• Troubleshooting
• Contributing
• Tests

This app reads the following Query String Parameters:

• returnUrl - After the user logs in, he is redirected to the returnUrl. This parameter should be UTF-8 encoded (as of javascript's encodeURIComponent). The returnUrl only works for the store's domain.

• oAuthRedirect - If this parameter is present, the user is directly redirected to the given OAuth Provider page before logging in, instead of displaying the login options. For this to work, the given OAuth Provider must be one of the login options. The parameter value is case sensitive and must be Google, Facebook or the registered name of the chosen OAuth Provider.

• userEmail - The default value for user email fields.

• flowState - The default state of the login flow to begin in. The possible values are from an enum with the following strings:

  • createPass - Create password state. When this is used, the query string userEmail must also be defined. On page view, an email will be sent to the user with the code required to create password.

This app uses our store builder with the blocks architecture. To know more about Store Builder click here.

We add the login as a block in our Store Header.

To configure or customize this app, you need to import it in your dependencies in manifest.json.

Then, add login or login-content block into your app theme as we do in our Store theme app. login-content is just the login form and login contains the login form and adds the possibility of other display modes such as pop-up.

Now, you can change the behavior of the login block that is in the store header. See an example of how to configure:

This app also uses SVG icons from store-icons, which means any icons used by it can be customized. Use icon-profile, icon-eye-sight and icon-arrow-back blocks to configure these icons via props, if you wish to change their default size(height and width) or viewBox.

When implementing this app as a block, various inner blocks may be available. The following interface lists the available blocks within login and login-content and describes if they are required or optional.

For now these blocks do not have any required or optional blocks.

Configuration

Through the Storefront, you can change the login's behavior and interface. However, you also can make in your theme app, as Store theme does.

Prop name	Type	Description	Default value
optionsTitle	String	Set title of login options	-
emailAndPasswordTitle	String	Set title of login with email and password	-
accessCodeTitle	String	Set title of login by access code	-
emailPlaceholder	String	Set placeholder to email input	-
passwordPlaceholder	String	Set placeholder to password input	-
showPasswordVerificationIntoTooltip	Boolean	Set show password format verification as tooltip	-
acessCodePlaceholder	String	Set placeholder to access code input	-
showIconProfile	Boolean	Enables icon hpa-profile	-
iconSize (DEPRECATED - use icon blocks instead)	Number	Set size of the profile icon	-
iconLabel	String	Set label of the login button	-
hideIconLabel	boolean	Whether the Login button label should be hidden (true) or not (false).	false
labelClasses	String	Label's classnames	-
providerPasswordButtonLabel	String	Set Password login button text	-
hasIdentifierExtension	Boolean	Enables identifier extension configurations	-
identifierPlaceholder	String	Set placeholder for the identifier extension	-
invalidIdentifierError	String	Set error message for invalid user identifier	-
mirrorTooltipToRight	Boolean	Makes login tooltip open towards the right side	false
logInButtonBehavior	Enum	Set log in button behavior. "popover" for popover, "link" for a link to the /login page	"popover"
accountOptionsButtonBehavior	Enum	Set account options button behavior. "popover" for popover, "link" for a link to the /account page	"popover"
accountOptionLinks	Array	Determines more specific account option links to replace the My Account link. Each array element is an object with the properties: label [string] - Link text path [string] - Relative path to where the link leads cssClass [string] - CSS class the link receives	-
termsAndConditions	String	Sets a markdown text below the login options, meant to warn the user about terms & conditions	-
hasGoogleOneTap	boolean	Defines whether the Google's One-tap sign-up and auto sign-in solution is enabled (true) or not (false) .	false
googleOneTapAlignment	enum	Defines pop-up alignment for the Google One-tap login. Possible values are Left and Right.	Right
googleOneTapMarginTop	string	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

Note that the Google One Tap props are in Beta. Although they are ready to be used, you can expect some UX and customization improvements.

You can also change the login-content's behaviour and interface through the Store front.

Prop name	Type	Description	Default value
isInitialScreenOptionOnly	Boolean	Set to show only the login options on the initial screen	true
defaultOption	Enum	Set the initial form to show. 0 for access code login, 1 for email and password login	0
optionsTitle	String	Set title of login options	-
emailAndPasswordTitle	String	Set title of login with email and password	-
accessCodeTitle	String	Set title of login by access code	-
emailPlaceholder	String	Set placeholder to email input	-
passwordPlaceholder	String	Set placeholder to password input	-
showPasswordVerificationIntoTooltip	Boolean	Set show password format verification as tooltip	-
acessCodePlaceholder	String	Set placeholder to access code input	-
providerPasswordButtonLabel	String	Set Password login button text	-
hasIdentifierExtension	Boolean	Enables identifier extension configurations	-
identifierPlaceholder	String	Set placeholder for the identifier extension	-
invalidIdentifierError	String	Set error message for invalid user identifier	-
termsAndConditions	String	Sets a markdown text below the login options, meant to warn the user about terms & conditions	-

This app can be extended through the plugins.json file of the store builder. The extension is only allowed for enterprise clients and can change the login functionality. It is explained in the following section.

User Identifier Extension

The Email/Password login takes two inputs:

• The user email (his identifier)
• The user password

The User Identifier Extension allows other identifiers to be used in the login form, as long as it can be resolved to the user email. For example, if your account stores the National Identity Document of each user, the Email/Password login would be changed to ask for the following two inputs:

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

There is a limitation to this feature. Every user must have an email to be logged in, so the user identifier must be able to be resolved to an email. If you want to use an identifier other than the email, you must create a resolver app (or an extension app) that returns an email, given an identifier. For example, imagine the user John, whose email is john@example.com and whose National Identity Document is 12345. When he types his document (12345), your app must receive the 12345, find out that it belongs to John, find out that John's email is john@example.com and return this email to the login app.

When an extension app returns an email to the login app, it acts like the user just typed in that email. So if it returns null, for example, a message like "The email is invalid" will appear. This message, along with some others, may be edited in the Store Front, as described in the Blocks API section (eg. "The User Identifier Extension is invalid").

Creating the User Identifier Extension App

To create your extension app, there are five steps you must worry about.

• First, you must add login as your app's dependency. In the manifest.json file:

• Second, you need to add the store builder to your app. In the manifest.json file:

• Third, you must extend the user-identifier interface defined by the login app. You can choose any interface name you want, which will be represented here by {{InterfaceName}}. You will need to create a component for that interface, but for now it will be represented by {{ComponentName}}. In the store/interfaces.json file:

• Fourth, you must plug in your interface to the login app. In the store/plugins.json file:

• Fifth, you need to create the component that you decided to name {{ComponentName}}. This component will replace the email input in the login form. This means that it could render anything, like a File Uploader or a simple Text Input which takes a National Identity Document. Just remember that this component must know how to convert the data it receives to an email. This is done by registering a callback function that returns an email whithin the login app. It will be defined in the file react/{{ComponentName}}.js. The following example is a good template to be used, and is commented so you understand each of its parts:

After following the five steps, your extension app will be good to go. Just install it in your account and it will replace the email Input in the login form.

This app provides some CSS classes as an API for style customization.

To use this CSS API, you must add the styles builder and create an app styling CSS file.

1. Add the styles builder to your manifest.json:

2. Create a file called vtex.login.css inside the styles/css folder. Add your custom styles:

CSS namespaces

Class name	Description	Component Source
container	Login main container	LoginComponent
contentInitialScreen	Login Content initial screen	LoginContent
contentFormVisible	Login Content form	LoginContent
profile	Profile email or name when logged in	LoginComponent
label	Icon label	LoginComponent
optionsSticky	Login options in sticky mode	LoginOptions
optionsList	Login options list	LoginOptions
optionsListItem	Login options item	LoginOptions
optionsListItemContainer	Container in Login options	LoginOptions
accessCodeOptionBtn	Access Code login option button	LoginOptions
emailPasswordOptionBtn	Email/ Password login option button	LoginOptions
facebookOptionBtn	Facebook login option button	OAuth
googleOptionBtn	Google login option button	OAuth
customOAuthOptionBtn	Custom OAuth login option button	OAuth
oauthProvider	OAuth provider name	OAuth
inputContainer	Any input container	CodeConfirmation, EmailAndPassword, EmailVerification, RecoveryPassword
inputContainerAccessCode	Access code input container	CodeConfirmation, RecoveryPassword
inputContainerPassword	Password input container	EmailAndPassword, RecoveryPassword
inputContainerEmail	Email input container	EmailAndPassword, EmailVerification
emailVerification	Email verification form	EmailAndPassword, EmailVerification, RecoveryPassword
emailForm	Email form to send access code	EmailVerification
emailAndPasswordForm	Form containing email and password	EmailAndPassword
forgotPasswordForm	"Forgot Password" form	RecoveryPassword
formLinkContainer	Container for links	EmailAndPassword
arrowUp	Arrow up	LoginComponent
buttonLink	Button link	LoginComponent
formError	Error form	LoginComponent
content	Login Content container	LoginContent
content--emailVerification	Container during emailVerification flow	LoginContent
content--emailAndPassword	Container during emailAndPassword flow	LoginContent
content--codeConfirmation	Container during codeConfirmation flow	LoginContent
content--accountOptions	Container during accountOptions flow	LoginContent
content--recoveryPassword	Container during recoveryPassword flow	LoginContent
button	Any button	AccountOptions, LoginOptions, OAuth
sendButton	Buttons sending informations	CodeConfirmation, EmailAndPassword, EmailVerification, RecoveryPassword
buttonSocial	Button to social media	OAuth
buttonDanger	Danger button	LoginOptions
backButton	Back button	GoBackButton
accountOptions	Account options container	AccountOption
codeConfirmation	Code Confirmation container	CodeConfirmation
formTitle	Form Title	FormTitle
formSubtitle	Form Subtitle	FormTitle
box	Login box	LoginContent
contentContainer	Login content container	LoginContent
formFooter	Form footer container	FormFooter
contentForm	Login Content form	LoginContent
contentAlwaysWithOptions	Login content with options	LoginContent
options	Login Options container	LoginOptions
tooltipContainer	Tooltip Container	Tooltip
tooltipContainerTop	Tooltip Top	Tooltip
tooltipContainerLeft	Tooltip Left	Tooltip
termsAndConditions	Container below login options	LoginContent
forgotPasswordLink	Link to create new password flow	EmailAndPassword
dontHaveAccount	Link to create account flow	EmailAndPassword
eyeIcon	Button that makes password visible	PasswordInput

You can check if others are passing through similar issues here. Also feel free to open issues or contribute with pull requests.

Check it out how to contribute with this project.

To execute our tests go to react/ folder and run yarn test