The Stormpath API will shut down on 8/17/2017 at noon PST. Learn More in our 
Building forms has never really been any fun. But with the new custom forms feature that we’ve added to the Stormpath React SDK, it suddenly is. This custom forms functionality means you’ll have the ability to plug in your own markup to the forms for user login, registration and reset password without having to think about any of the logic behind them.
React developers can now simply style the form quickly, and Stormpath will take care of all the rest.
Let’s Build a User Form in React
Before we get started: If you haven’t played around with React or want to try these examples in a sample application, then take a look at our previous blog post Build a React.js Application With User Authentication or play along with the example project.
Default Markup
Forms in the Stormpath React SDK still work as previously. If no markup is provided, the form will simply render with the default Bootstrap markup, i.e.
|
1 2 |
<LoginForm /> |
This actually turns into:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 |
<LoginForm> <div className='sp-login-form'> <div className="row"> <div className="col-xs-12"> <div className="form-horizontal"> <div className="form-group"> <label htmlFor="spEmail" className="col-xs-12 col-sm-4 control-label">Email</label> <div className="col-xs-12 col-sm-4"> <input className="form-control" id="spUsername" name="username" placeholder="Username or Email" /> </div> </div> <div className="form-group"> <label htmlFor="spPassword" className="col-xs-12 col-sm-4 control-label">Password</label> <div className="col-xs-12 col-sm-4"> <input type="password" className="form-control" id="spPassword" name="password" placeholder="Password" /> </div> </div> <div className="form-group"> <div className="col-sm-offset-4 col-sm-4"> <p className="alert alert-danger" spIf="form.error"><span spBind="form.errorMessage" /></p> <button type="submit" className="btn btn-primary">Login</button> <Link to="/forgot" className="pull-right">Forgot Password</Link> </div> </div> </div> </div> </div> </div> </LoginForm> |
Custom Markup for Login Forms
Now, adding your own markup to user forms is easy. When markup is passed to the form, the form will automatically process that markup and bind common input fields and buttons depending on their input type and name. The conditions (spIf) and bindings (spBind) available depend on the form used.
To demonstrate this, a simple, stripped-down login form can look like:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
<LoginForm> <p> <input type="text" name="username" placeholder="Username" /> </p> <p> <input type="password" name="password" placeholder="Password" /> </p> <p spIf="form.error"> <strong>Error:</strong> <span spBind="form.errorMessage" /> </p> <p> <input type="submit" value="Login" /> </p> </LoginForm> |
Field Mapping
As previously mentioned, when markup is provided to a form, that markup is processed and input fields are mapped, with available fields varying by form.
For the login form, the valid fields are username (or login, the username to login with) and password (the password to login with).
In order to map an input to the username field, all you have to do is to set the input name to the field name:
|
1 2 |
<input type="text" name="username" /> |
If you’re interested in seeing what fields can be mapped for the registration or reset password form, take a look at the Stormpath React documentation.
Conditional Statements
In order to control what is being shown, each form has a specific set of spIf conditions that you can use.
For the login form, the available conditions are form.processing, which is true when the form is loading, and form.error, which is set to true when there is a bindable error message.
In order to only show an element during a form.error, all you need to do is set the spIf attribute:
|
1 2 3 4 |
<p spIf="form.error"> Form error occurred. Please try again. </p> |
If you’re interested in seeing what spIf conditions are available for the registration or reset password form, take a look at the Stormpath React documentation.
Bind Values
In order to show certain texts, spBind can be added on an element to bind that element to a value. For the login form, the bindable values are form.errorMessage, which is an error message present when the form.error condition is true.
So in order to show an error message during a form.error, all you need to do is to set the spBind attribute on an element, as shown below:
|
1 2 3 4 |
<p spIf="form.error"> <span spBind="form.errorMessage" /> </p> |
If you’re interested in seeing what spBind values are available for the registration or reset password form, take a look at the Stormpath React documentation.
Intercept Form Submit
If an onSubmit attribute is set on a form, then the handled function attached to that attribute will be called once a form is submitted. The handler that you attach can be used to do custom error validation or format the data that is posted to Stormpath, i.e. providing your own onSubmit handler for the login form would look like:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 |
class LoginPage extends React.Component { onFormSubmit(e, next) { var data = e.data; // Require passwords to be at least 10 characters. if (data.password.length < 10) { return next(new Error('Password must be at least 10 characters long.')); } // Force usernames to be in lowercase. data.username = data.username.toLowerCase(); next(null, data); } render() { return <LoginForm onSubmit={this.onFormSubmit.bind(this)} />; } } |
Summary
As you’ve just seen demonstrated, the new custom forms feature really makes building forms a lot easier. It’s one of the many improvements we have added to the React SDK lately.
If you have any feedback on the custom forms feature or the React SDK in general. Feel free to leave that in the comment section below.