Lock Instance Lifecycle

Relevant source files

• src/connection/database/actions.js
• src/core.js
• src/core/actions.js
• src/core/index.js
• src/core/web_api.js

Purpose and Scope

This page documents the complete lifecycle of a Lock instance from construction through destruction. It covers the initialization process, state setup, rendering lifecycle, authentication flows, and cleanup procedures. The lifecycle is managed through an immutable state store with reactive observers that trigger UI updates.

For information about the state management system itself, see State Management. For details on the public API methods, see Public API Classes. For authentication flow details, see Authentication Methods.

---

Lifecycle Phases Overview

The Lock instance lifecycle consists of six distinct phases:

Phase	Trigger	Key Functions	State Changes
Construction	new Auth0Lock()	Base constructor	Creates instance ID, event emitter
Setup	Constructor → setupLock()	l.setup(), webApi.setupClient()	Initializes persistent state, syncs remote data
Display	show() → openLock()	l.render(), observer fires	Sets rendering = true, filters connections
Interaction	User actions	validateAndSubmit(), logIn()	Sets submitting, loggedIn, globalError
Closure	hide() → closeLock()	l.stopRendering(), l.reset()	Clears transient state, resets fields
Destruction	destroy() → removeLock()	removeEntity()	Removes from store entirely

Sources: src/core.js24-231 src/core/actions.js18-150 src/core/index.js17-708

---

Lifecycle State Diagram

Sources: src/core.js24-166 src/core/actions.js77-145 src/core/index.js106-159

---

Construction Phase

The construction phase begins when new Auth0Lock(clientID, domain, options) or new Auth0LockPasswordless(clientID, domain, options) is called.

Base Constructor Sequence

Sources: src/core.js24-86 src/core/actions.js18-40 src/core/index.js17-46 src/sync.js (go function), src/sanitizer.js (initSanitizer)

Initial State Setup

The setup() function src/core/index.js17-46 creates the initial immutable state using dataFns(['core']) utilities. The state is stored at store.getIn(['lock', id, 'core']):

After l.setup() returns, the state is initialized with i18n: m = i18n.initI18n(m) src/core/index.js44 which adds language dictionaries.

Sources: src/core/index.js17-399 src/i18n/index.js (initI18n)

---

Display Lifecycle

Opening the Lock (show)

When lock.show(opts) is called, it triggers openLock() src/core/actions.js77-110:

Sources: src/core/actions.js77-110 src/core/index.js401-708

Runtime Options Override

The overrideOptions() function src/core/index.js655-708 allows dynamic reconfiguration at display time:

Option	Effect	Stored in
allowedConnections	Filters visible connections	core.transient.allowedConnections
flashMessage	Shows info/error/success banner	core.transient.global{Type}
auth.params	Overrides auth parameters	core.transient.authParams
theme.primaryColor	Changes primary color	core.transient.ui.primaryColor
theme.logo	Changes logo	core.transient.ui.logo
language	Changes display language	core.transient.ui.language
languageDictionary	Custom translations	core.transient.ui.dict
rememberLastLogin	Toggles credential memory	core.transient.rememberLastLogin

Transient options override persistent options via getUIAttribute() src/core/index.js240-242

Sources: src/core/index.js236-708

Render Observer Setup and Execution

The observer is established in the Base constructor src/core.js87-166 immediately after setupLock() completes:

The observe() function src/store/index.js6-14 implements change detection using Immutable.js .equals():

Key Functions:

• observe(trigger, id, callback) src/store/index.js6-14 - Registers observer
• l.rendering(m) src/core/index.js153-155 - Returns tget(m, 'render', false)
• this.engine.render(m) - Calls engine's render method to get screen object
• render(containerID, props) src/ui/box/index.js - React rendering
• remove(containerID) src/ui/box/index.js - React unmounting

Sources: src/core.js87-166 src/store/index.js6-14 src/core/index.js153-155 src/ui/box/index.js

---

Authentication Lifecycle

Submission Flow

The authentication lifecycle involves state transitions through the submitting flag:

Sources: src/core/actions.js167-265 src/core/index.js106-139

Submitting State Management

The setSubmitting() function src/core/index.js106-115 manages the submission overlay and global message state:

Submitting State Effects

State	Value	UI Effect	API State
submitting = true	Set via setSubmitting(m, true)	Submit overlay shown, button disabled	API call in progress
submitting = false, error = ''	Set via setSubmitting(m, false)	Overlay hidden, form editable	API call complete (success)
submitting = false, error = 'msg'	Set via setSubmitting(m, false, 'msg')	Overlay hidden, error banner shown	API call failed

Usage Throughout Authentication Flows

Invocation Points:

• Set True: validateAndSubmit() src/core/actions.js171 when validation passes
• Set False (success): logInSuccess() src/core/actions.js224 if autoclose disabled
• Set False (error): logInError() src/core/actions.js253-257 after error handling
• Also used in: signUp(), resetPassword(), checkSession() flows

Related Functions:

• submitting(m) src/core/index.js113-115 - Getter: tget(m, 'submitting', false)
• suppressSubmitOverlay(m) src/core/index.js165-167 - Can disable overlay (used for SSO)
• globalError(m) src/core/index.js121-123 - Returns error message for banner
• clearGlobalError(m) src/core/index.js125-127 - Clears core.transient.globalError

Sources: src/core/index.js106-167 src/core/actions.js167-257 src/connection/database/actions.js24-260

Hook Execution Mechanism

Hooks are executed through the runHook() method src/core.js209-230 which differentiates between public hooks (configured by users) and engine hooks (internal).

Hook Execution Flow

Hook Invocation Points

Hook Name	Invocation Point	Code Location	Arguments	Blocking
didInitialize	After setupLock() completes	src/core/actions.js35	(options)	No - return value ignored
willShow	During openLock(), before rendering	src/core/actions.js105	(opts)	No - return value ignored
loggingIn	In logIn(), before webApi.logIn()	src/core/actions.js193	(context, callback)	Yes - must call callback()
signingUp	In signUp(), before webApi.signUp()	src/connection/database/actions.js144	(context, callback)	Yes - must call callback()

Blocking Hook Example

If user configures options.hooks.loggingIn, they receive:

• context - Always null currently src/core/actions.js191
• callback - Function that must be called to continue authentication

Configuration Example:

Sources: src/core.js209-230 src/core/actions.js35-201 src/connection/database/actions.js139-156 src/core/index.js15-234

---

Closure and Cleanup

Close Flow

The closeLock() function src/core/actions.js112-145 handles cleanup differently based on l.ui.appendContainer(m), which determines modal vs inline mode:

Close Mode Comparison

Aspect	Modal Mode (appendContainer=true)	Inline Mode (appendContainer=false)
Detection	l.ui.appendContainer(m) src/core/index.js246	Options specified container: 'selector'
Rendering	Creates <div id="auth0-lock-container-N">	Renders into existing container
Close Animation	1000ms delay before state reset	Immediate state reset
Reason for Delay	Allows CSS fade-out animation	No animation needed (stays in DOM)
State Operations	Two separate swap() calls	Single swap() call
stopRendering	Yes - tremove(m, 'render') src/core/index.js157-159	Not called explicitly

State Cleanup Chain

Both modes execute the same cleanup chain (timing differs):

1. hideInvalidFields(m) src/field/index.js - Clears field validation errors
2. l.reset(m) src/core/index.js405 - Clears core.transient.* state
3. clearFields(m) src/field/index.js - Clears all field values

Sources: src/core/actions.js112-145 src/core/index.js157-405 src/field/index.js

State Reset via dataFns

The reset() function src/core/index.js405 is imported from dataFns(['core']) src/core/index.js13 and removes all transient state at core.transient.* while preserving persistent configuration at core.*:

State Organization

reset() Behavior

Transient State Cleared by reset()

Path	Purpose	Setter	Getter
core.transient.submitting	Form submission in progress	setSubmitting() src/core/index.js106	submitting() src/core/index.js113
core.transient.globalError	Error banner message	setGlobalError() src/core/index.js117	globalError() src/core/index.js121
core.transient.globalSuccess	Success banner message	setGlobalSuccess() src/core/index.js129	globalSuccess() src/core/index.js133
core.transient.globalInfo	Info banner message	setGlobalInfo() src/core/index.js141	globalInfo() src/core/index.js145
core.transient.render	UI rendering flag	render() src/core/index.js401	rendering() src/core/index.js153
core.transient.loggedIn	Authentication success	setLoggedIn() src/core/index.js407	loggedIn() src/core/index.js411
core.transient.rememberLastLogin	Override from show()	overrideOptions() src/core/index.js694	ui.rememberLastLogin() src/core/index.js263
core.transient.allowedConnections	Override from show()	overrideOptions() src/core/index.js659	allowedConnections() src/core/index.js476
core.transient.authParams	Override from show()	overrideOptions() src/core/index.js669	auth.params() src/core/index.js276
core.transient.ui.*	UI overrides from show()	overrideOptions() src/core/index.js673-691	getUIAttribute() src/core/index.js240

This separation enables show(opts) to be called multiple times with different transient configurations without permanently modifying the persistent instance state.

Sources: src/core/index.js13-708 src/utils/data_utils.js src/core/actions.js127-133

---

Destruction Phase

Complete Removal

The destroy() method triggers removeLock() src/core/actions.js147-150:

After destruction:

• The entity is removed from the store src/store/index.js44-46
• Calling show() throws: "The Lock can't be opened again after it has been destroyed" src/core/actions.js80
• The Base instance still exists but cannot interact with state
• Event listeners remain attached to the EventEmitter

Sources: src/core.js181-183 src/core/actions.js147-150 src/store/index.js44-46

---

State Management Integration

Observer Pattern

Lock uses an observer pattern to trigger UI updates when state changes:

Sources: src/store/index.js1-66 src/core.js87-166

Entity Update Pattern

All state changes use the swap(updateEntity, ...) pattern src/store/index.js28-30:

This ensures:

• All updates are atomic
• Observers always fire with correct old/new state
• No race conditions from concurrent updates
• Immutability prevents accidental mutations

Sources: src/store/index.js24-30 src/core/actions.js102-173

Transient vs Persistent State

The state is organized into persistent and transient sections:

State Path	Purpose	Cleared on	Retrieved via
core.*	Persistent config	Never (until destroy)	get(m, key)
core.transient.*	Runtime flags	reset() on close	tget(m, key)
core.transient.ui.*	UI overrides	reset() on close	tgetUI(m, key)

The getUIAttribute() function src/core/index.js240-242 implements fallback logic:

This allows show(opts) to temporarily override configuration without permanently modifying the instance.

Sources: src/core/index.js13-270 src/utils/data_utils.js (dataFns implementation)

---

Lifecycle Summary Table

Phase	Entry Point	State Changes	Store Operations	UI Updates	Reversible?
Construction	new Auth0Lock()	Instance ID created	None yet	None	No
Setup	Constructor → setupLock()	Persistent state initialized	setEntity('lock', id, m)	None	No
Display	show() → openLock()	render=true, transient overrides	updateEntity('lock', id, ...)	Observer → render()	Yes (can hide)
Interaction	User actions	submitting, globalError, field values	updateEntity('lock', id, ...)	Re-renders on each update	Yes (can retry)
Closure	hide() → closeLock()	Transient state cleared	updateEntity('lock', id, ...)	Observer → remove()	Yes (can show again)
Destruction	destroy() → removeLock()	Entity removed	removeEntity('lock', id)	Permanent removal	No

Sources: src/core.js24-231 src/core/actions.js18-150 src/core/index.js1-709