@super-formal/user-forms
Common user forms (log in, sign up, etc.) as react components to get your app going quick and well.
Index
-
builders
propadapters
propstate
propreactions
proponSubmitClick
propuserIDLabel
propsubmitLabel
propshowErrorMesssagesAtTop
prophideUserIDField
prophideEmailField
propdontValidateFieldsBeforeSending
propvalidateUserIDAfterXSecondsOfTyping
proponValidateUserID
propshowUserIdAlreadyInUseError
prop
-
The
ResetPasswordForm
Componentbuilders
propadapters
propstate
propreactions
proponSubmitClick
propuserIDLabel
propsubmitLabel
propshowErrorMesssagesAtTop
propdontValidateFieldsBeforeSending
propshowPasswordHasBeenChangedSuccess
proppasswordHasBeenChangedMessage
propshowInvalidUsernameOrTokenError
propinvalidUsernameOrTokenMessage
prop
Installation
Using npm:
npm i -g npm
npm i --save @super-formal/user-forms
Using yarn:
yarn add @super-formal/user-forms
Basic Usage
After installing the package you can use it in your React project as follows:
import {
LoginForm,
SignupForm,
ForgotPasswordForm,
ResetPasswordForm,
} from '@super-formal/user-forms';
const DEFAULT_BUILDERS = {
'form': Form, // You have to define this component
'text': TextField, // You have to define this component
'button': Button, // You have to define this component
};
// inside your render() function
<div>
<LoginForm
builders={DEFAULT_BUILDERS}
onSubmitClick={(username, password) => {
// try to log the user in
}}
/>
<SignupForm
builders={DEFAULT_BUILDERS}
onSubmitClick={(username, email, password) => {
// try to sign the user up
}}
/>
<ForgotPasswordForm
builders={DEFAULT_BUILDERS}
onSubmitClick={(username, email) => {
// start the reset password procedure for this user
}}
/>
<ResetPasswordForm
builders={DEFAULT_BUILDERS}
onSubmitClick={(username, token, password) => {
// reset the user's password
}}
/>
</div>
Motivation
User forms are one of the first hurdles you encounter when trying to build an app. These components intend to make it easy to quickly set up the user forms and get going with the rest of the app.
LoginForm
Component
The The LoginForm
is a Form
with the following structure:
[
{type: "text", id: "userID"},
{type: "text", id: "password"},
{type: "button", id: "submit"}
]
It also has the implicit structural component {type: "form", id: "form"}
.
builders
prop
{Object<type: String, id: String>}
- required - The builders (React components) to use when building each of the structural components of the form. You should at least provide the following builders:
{
text: *your Text component*,
button: *your Button component*
}
See the Form.builders
prop's docs for more information.
adapters
prop
{Object<String, Function>}
- optional - The adapters that modify the state provided by the form to each of your components. By default an identity function is used as an adapter for each field in the form. This means the state and reactions are passed from the Form to the components as props without modifications. Here's a template you can use for the login form adapters:
adapters={{
form: ({
errorMessages: Array<String> - A list of error messages to display at the top of the form.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
userID: ({
hint: String - The label for the user field.
value: String - The value typed into the user field.
hasError: Boolean - `true` if this field has an error.
errorMessage: String - The error message associated with this field.
onChange: Function - The callback to be called when the value of the field changes.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
password: ({
hint: String - The label for the password field.
value: String - The value typed into the password field.
hasError: Boolean - `true` if this field has an error.
errorMessage: String - The error message associated with this field.
password: Boolean - `true`.
onChange: Function - The callback to be called when the value of the field changes.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
submit: ({
label: String - The label to show in the button
onClick: Function - The callback to be called when the submit button is clicked.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
})
}}
See the Form.adapters
prop's docs for more information.
state
prop
{Object<String, Object<String, Any>>}
- optional - Any additional state values to be passed as props to the fields in the form. Do not pass callbacks to the fields through the state
prop. Use the reactions
prop for that instead.
See the Form.state
prop's docs for more information.
reactions
prop
{Object<String, Object<String, Function | Array<Function> | ChainReaction>>}
- optional - Any additional callback values to be passed as props to the fields in the form. Do not pass state props to the fields through the reactions
prop. Use the state
prop for that instead.
See the Form.reactions
prop's docs for more information.
onSubmitClick
prop
{Function}
- optional - A callback to call when the submit
button is clicked. It has the following signature:
(username, password) => {
// log the user in
}
userIDLabel
prop
{String}
- optional - The label (hint) to show for the userID
field. Defaults to "Email"
.
submitLabel
prop
{String}
- optional - The label to show on the submit
button. Defaults to "Log In"
.
showErrorMesssagesAtTop
prop
{Boolean}
- optional - Defualts to false
. true
if you want to show all errors at the top of the form. Otherwise, each error will be displayed under its respective field.
showMismatchingUserAndPasswordError
prop
{Boolean}
- optional - Defualts to false
. true
if you want to show an error message indicating that the submitted userID
and password
values failed to log in. Set this to true
after you send a log in request and your server fails to log in the user.
dontValidateFieldsBeforeSending
prop
{Boolean}
- optional - Defualts to false
. true
if you don't want the form to validate the inputs before sending. They are validated by default. The validation simply verifies that the userID
and password
fields are not empty.
SignupForm
Component
The The SignupForm
is a Form
with the following structure:
[
{type: "text", id: "username"},
{type: "text", id: "email"},
{type: "text", id: "password"},
{type: "text", id: "confirmPassword"},
{type: "button", id: "submit"}
]
It also has the implicit structural component {type: "form", id: "form"}
.
builders
prop
{Object<type: String, id: String>}
- required - The builders (React components) to use when building each of the structural components of the form. You should at least provide the following builders:
{
text: *your Text component*,
button: *your Button component*
}
See the Form.builders
prop's docs for more information.
adapters
prop
{Object<String, Function>}
- optional - The adapters that modify the state provided by the form to each of your components. By default an identity function is used as an adapter for each field in the form. This means the state and reactions are passed from the Form to the components as props without modifications. Here's a template you can use for the login form adapters:
adapters={{
form: ({
errorMessages: Array<String> - A list of error messages to display at the top of the form.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
username: ({
hint: String - The label for the username field.
value: String - The value typed into the username field.
hasError: Boolean - `true` if this field has an error.
errorMessage: String - The error message associated with this field.
onChange: Function - The callback to be called when the value of the field changes.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
email: ({
hint: String - The label for the user field.
value: String - The value typed into the user field.
hasError: Boolean - `true` if this field has an error.
errorMessage: String - The error message associated with this field.
onChange: Function - The callback to be called when the value of the field changes.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
password: ({
hint: String - The label for the password field.
value: String - The value typed into the password field.
hasError: Boolean - `true` if this field has an error.
errorMessage: String - The error message associated with this field.
password: Boolean - `true`.
onChange: Function - The callback to be called when the value of the field changes.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
confirmPassword: ({
hint: String - The label for the confirm password field.
value: String - The value typed into the confirm password field.
hasError: Boolean - `true` if this field has an error.
errorMessage: String - The error message associated with this field.
password: Boolean - `true`.
onChange: Function - The callback to be called when the value of the field changes.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
submit: ({
label: String - The label to show in the button
onClick: Function - The callback to be called when the submit button is clicked.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
})
}}
See the Form.adapters
prop's docs for more information.
state
prop
{Object<String, Object<String, Any>>}
- optional - Any additional state values to be passed as props to the fields in the form. Do not pass callbacks to the fields through the state
prop. Use the reactions
prop for that instead.
See the Form.state
prop's docs for more information.
reactions
prop
{Object<String, Object<String, Function | Array<Function> | ChainReaction>>}
- optional - Any additional callback values to be passed as props to the fields in the form. Do not pass state props to the fields through the reactions
prop. Use the state
prop for that instead.
See the Form.reactions
prop's docs for more information.
onSubmitClick
prop
{Function}
- optional - A callback to call when the submit
button is clicked. It has the following signature:
(username, email, password) => {
// sign the user up
}
Note that the username parameter will be removed from the signature if the hideUserIDField
is set to true
, and the email parameter will removed from the signature if the hideEmailField
is set to true
.
userIDLabel
prop
{String}
- optional - The label (hint) to show for the userID
field. Defaults to "Username"
.
submitLabel
prop
{String}
- optional - The label to show on the submit
button. Defaults to "Sign Up"
.
showErrorMesssagesAtTop
prop
{Boolean}
- optional - Defualts to false
. true
if you want to show all errors at the top of the form. Otherwise, each error will be displayed under its respective field.
hideUserIDField
prop
{Boolean}
- optional - Defaults to false
. If true
this removes the userID
field from the structure of this Form
. Use this if the user accounts in your app/service only require an email and a password for users to join.
hideEmailField
prop
{Boolean}
- optional - Defaults to false
. If true
this removes the email
field from the structure of this Form
. Use this if the user accounts in your app/service only require a username and a password for users to join.
dontValidateFieldsBeforeSending
prop
{Boolean}
- optional - Defualts to false
. true
if you don't want the form to validate the inputs before sending. They are validated by default. The validation simply verifies that the userID
, email
, password
, and confirmPassword
fields are not empty. It also verifies that the email
value has a valid email format. It also verifies that the password
and confirmPassword
values are the same.
validateUserIDAfterXSecondsOfTyping
prop
{Number}
- optional - Defaults to undefined
. Set to a positive integer to indicate how many seconds after the user changes the value for the username
field (or the email
field if hideUserIDField
is set to true
). If the user changes the value again before the specified number of seconds had passed then the validation will be delayed further. After the specified time passes without interruption then the callback in the onValidateUserID
prop is called.
onValidateUserID
prop
{Function}
- optional - Defaults to undefined
- Set to a callback function with the signature (userIDValue as String) => {// verify that user ID is valid / available}
. This callback is called once the the username
value changes (or the email
value if hideUserIDField
is set to true
), see the description for the validateUserIDAfterXSecondsOfTyping
prop. You are supposed to verify whether the userID is valid and available, and raise the showUserIdAlreadyInUseError
flag otherwise.
showUserIdAlreadyInUseError
prop
{Boolean}
- optional - Defaults to false
. If true
then an error message will be passed to the form saying tha that the entered userID is not available.
ForgotPasswordForm
Component
The The ForgotPasswordForm
is a Form
with the following structure:
[
{type: "text", id: "username"},
{type: "text", id: "email"},
{type: "button", id: "submit"}
]
It also has the implicit structural component {type: "form", id: "form"}
.
builders
prop
{Object<type: String, id: String>}
- required - The builders (React components) to use when building each of the structural components of the form. You should at least provide the following builders:
{
text: *your Text component*,
button: *your Button component*
}
See the Form.builders
prop's docs for more information.
adapters
prop
{Object<String, Function>}
- optional - The adapters that modify the state provided by the form to each of your components. By default an identity function is used as an adapter for each field in the form. This means the state and reactions are passed from the Form to the components as props without modifications. Here's a template you can use for the login form adapters:
adapters={{
form: ({
errorMessages: Array<String> - A list of error messages to display at the top of the form.
successMessages: Array<String> - A list of success messages to display at the top of the form.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
username: ({
hint: String - The label for the username field.
value: String - The value typed into the username field.
hasError: Boolean - `true` if this field has an error.
errorMessage: String - The error message associated with this field.
onChange: Function - The callback to be called when the value of the field changes.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
email: ({
hint: String - The label for the email field.
value: String - The value typed into the email field.
hasError: Boolean - `true` if this field has an error.
errorMessage: String - The error message associated with this field.
onChange: Function - The callback to be called when the value of the field changes.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
submit: ({
label: String - The label to show in the button
onClick: Function - The callback to be called when the submit button is clicked.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
})
}}
See the Form.adapters
prop's docs for more information.
state
prop
{Object<String, Object<String, Any>>}
- optional - Any additional state values to be passed as props to the fields in the form. Do not pass callbacks to the fields through the state
prop. Use the reactions
prop for that instead.
See the Form.state
prop's docs for more information.
reactions
prop
{Object<String, Object<String, Function | Array<Function> | ChainReaction>>}
- optional - Any additional callback values to be passed as props to the fields in the form. Do not pass state props to the fields through the reactions
prop. Use the state
prop for that instead.
See the Form.reactions
prop's docs for more information.
onSubmitClick
prop
{Function}
- optional - A callback to call when the submit
button is clicked. It has the following signature:
(username, email) => {// start the reset password procedure for this user}
Note that the username parameter will be removed from the signature if the hideUserIDField
is set to true
, and the email parameter will be removed from the signature if the hideEmailField
is set to true
.
userIDLabel
prop
{String}
- optional - The label (hint) to show for the username
field. Defaults to "Username"
.
submitLabel
prop
{String}
- optional - The label to show on the submit
button. Defaults to "Request Token"
.
showErrorMesssagesAtTop
prop
{Boolean}
- optional - Defualts to false
. true
if you want to show all errors at the top of the form. Otherwise, each error will be displayed under its respective field.
dontValidateFieldsBeforeSending
prop
{Boolean}
- optional - Defualts to false
. true
if you don't want the form to validate the inputs before sending. They are validated by default. The validation simply verifies that the username
and email
fields are not empty.
showResetTokenHasBeenSentSuccess
prop
{Boolean}
- optional - Defaults to false
. true
if you want to show a message at the top of the form informing the user that the reset token has been successfully sent to their email account.
resetTokenHasBeenSentMessage
prop
{String}
- optional - Defaults to "A reset token has been sent to your email account"
. You can set this value to a different message to show to the user. This mesasge is displayed at the top of the form when the showResetTokenHasBeenSentSuccess
prop is set to true
.
hideUserIDField
prop
{Boolean}
- optional - Defaults to false
. If true
then the userID
field is removed from the structure of this Form
. Use this if the user accounts in your app/service only require an email and a password for users to join.
hideEmailField
prop
{Boolean}
- optional - Defaults to false
. If true
then the email
field is removed from the structure of this Form
.
ResetPasswordForm
Component
The The ResetPasswordForm
is a Form
with the following structure:
[
{type: "text", id: "userID"},
{type: "text", id: "token"},
{type: "text", id: "password"},
{type: "text", id: "confirmPassword"},
{type: "button", id: "submit"},
]
It also has the implicit structural component {type: "form", id: "form"}
.
builders
prop
{Object<type: String, id: String>}
- required - The builders (React components) to use when building each of the structural components of the form. You should at least provide the following builders:
{
text: *your Text component*,
button: *your Button component*
}
See the Form.builders
prop's docs for more information.
adapters
prop
{Object<String, Function>}
- optional - The adapters that modify the state provided by the form to each of your components. By default an identity function is used as an adapter for each field in the form. This means the state and reactions are passed from the Form to the components as props without modifications. Here's a template you can use for the login form adapters:
adapters={{
form: ({
errorMessages: Array<String> - A list of error messages to display at the top of the form.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
userID: ({
hint: String - The label for the userID field.
value: String - The value typed into the userID field.
hasError: Boolean - `true` if this field has an error.
errorMessage: String - The error message associated with this field.
onChange: Function - The callback to be called when the value of the field changes.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
token: ({
hint: String - The label for the token field.
value: String - The value typed into the token field.
hasError: Boolean - `true` if this field has an error.
errorMessage: String - The error message associated with this field.
onChange: Function - The callback to be called when the value of the field changes.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
password: ({
hint: String - The label for the password field.
value: String - The value typed into the password field.
hasError: Boolean - `true` if this field has an error.
errorMessage: String - The error message associated with this field.
password: Boolean - `true`.
onChange: Function - The callback to be called when the value of the field changes.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
confirmPassword: ({
hint: String - The label for the confirm password field.
value: String - The value typed into the confirm password field.
hasError: Boolean - `true` if this field has an error.
errorMessage: String - The error message associated with this field.
password: Boolean - `true`.
onChange: Function - The callback to be called when the value of the field changes.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
}),
submit: ({
label: String - The label to show in the button
onClick: Function - The callback to be called when the submit button is clicked.
}) => ({
thisKeyMatchesAPropForYourComponent: thisIsAValueForThatProp,
...
})
}}
See the Form.adapters
prop's docs for more information.
state
prop
{Object<String, Object<String, Any>>}
- optional - Any additional state values to be passed as props to the fields in the form. Do not pass callbacks to the fields through the state
prop. Use the reactions
prop for that instead.
See the Form.state
prop's docs for more information.
reactions
prop
{Object<String, Object<String, Function | Array<Function> | ChainReaction>>}
- optional - Any additional callback values to be passed as props to the fields in the form. Do not pass state props to the fields through the reactions
prop. Use the state
prop for that instead.
See the Form.reactions
prop's docs for more information.
onSubmitClick
prop
{Function}
- optional - A callback to call when the submit
button is clicked. It has the following signature:
(username, token, password) => {
// reset the user's password
}
userIDLabel
prop
{String}
- optional - The label (hint) to show for the userID
field. Defaults to "Username"
.
submitLabel
prop
{String}
- optional - The label to show on the submit
button. Defaults to "Reset Password"
.
showErrorMesssagesAtTop
prop
{Boolean}
- optional - Defualts to false
. true
if you want to show all errors at the top of the form. Otherwise, each error will be displayed under its respective field.
dontValidateFieldsBeforeSending
prop
{Boolean}
- optional - Defualts to false
. true
if you don't want the form to validate the inputs before sending. They are validated by default. The validation verifies that the userID
, token
, password
, and confirmPassword
fields are not empty. Then it verifies that the values for the password
and confirmPassword
fields match.
showPasswordHasBeenChangedSuccess
prop
{Boolean}
- optional - Defaults to false
. true
if you want to show a message at the top of the form informing the user that the password to their account as been successfully reset.
passwordHasBeenChangedMessage
prop
{String}
- optional - Defaults to "Your password has been successfully updated."
. You can set this value to a different message to show to the user. This mesasge is displayed at the top of the form when the showPasswordHasBeenChangedSuccess
prop is set to true
.
showInvalidUsernameOrTokenError
prop
{Boolean}
- optional - Defaults to false
. true
if you want to show an error message at the top of the form informing the user that the provided username
or the token
values are invalid. You should set this to true
if the backend fails to validate the reset token for the user.
invalidUsernameOrTokenMessage
prop
{String}
- optional - Defaults to "The provided username and token are invalid. Password has not been reset."
. You can set this value to a different message to show to the user. This mesasge is displayed at the top of the form when the showInvalidUsernameOrTokenError
prop is set to true
.