Setting up Element

How to use @element/react with create-react-app

  1. Create your app

    # Create a new app
# Substitute your app's actual name here
npx create-react-app super-cool-app

cd super-cool-app

  2. Create an .npmrc file pointing to Element

  3. Add @element/react as a dependency of your project:

    # Install with yarn
yarn add @element/react

# Or install with NPM
npm i @element/react

  4. Convert the create-react-app to use SCSS

    1. Install sass
      yarn add sass
    2. Rename src/App.css and src/index.css to both have .scss extensions
    3. Update the import paths to those renamed SCSS files in src/App.js and src/index.js respectively

    Note: At this point, your app should still run! But you'll see the same default UI as you would have seen upon initial app creation. You can test this with yarn start

  5. Render a Element component

    You could pick any component, but as an example, let's try the LoginForm.

    1. Open the src/App.js file

    2. Import the LoginForm, LoginPage, and LegalFooter components from @element/react

      import {LoginForm, LoginPage, LegalFooter} from '@element/react'

    3. Make the App component render a LoginPage component

      import React from 'react'
import {LoginForm, LoginPage, LegalFooter} from '@element/react'
import './App.scss'

export default function App() {
  return (
    <LoginPage>
      <LoginForm onLogin={() => {}} />
      <LegalFooter />
    </LoginPage>
  )
}

  6. Run the app!

    yarn start

    Look! A login page! But it doesn't look very refined, what happened!?

    You've imported the Element JavaScript code, but not the Element SCSS

  7. Import the Element styles

    1. Tell sass to look in the node_modules directory when resolving @use paths

      1. Open the package.json file

      2. Modify the start script:

        "start": "SASS_PATH=./node_modules react-scripts start",

      For more information about this and other solutions to the problem of importing library SASS, please see Google's explanation of it here.

  1. Replace the contents of src/App.scss with these import statements:

    @use '@element/react/LoginForm';

  2. Run the app again!

    yarn start

    Note: if the app was still running from before, you'll have to restart it

    The app should run and you should see a nicely styled login page.

Next Steps

You've used Element to create a beautiful login page, but what's next?

Element Style System

We just got the Element styles imported into your project, but we didn't take any steps to configure those styles. If your use case calls for customizing Element styles, please see our style system documentation.

Add additional functionality to LoginForm

You probably noticed that the "log in" button on our login form doesn't do anything and that it doesn't have any forgot password or sign up functionality. Let's fix that!

The LoginForm component accepts several additional props to customize its functionality. Two of those are onForgotPassword, and onSignUp. Each of those props accepts a callback function. Passing them might look something like this:

<LoginPage>
  <LoginForm
    onLogin={(u, p) => alert(`username: ${u}\npassword: ${p}`)}
    onSignUp={() => alert('SignUp called')}
    onForgotPassword={() => alert('ForgotPassword called')}
  />
  <LegalFooter />
</LoginPage>

Notice that after you pass those props, buttons for forgot password and sign up have magically appeared on your page in an intelligent fashion, neat!

Internationalization

Finally, in many applications it's important to be able to translate the UI into different languages. Element React supports this through props. Every string that's displayed on the screen has a corresponding prop that allows you to pass an overriding value.

For example, try passing these two props:

<LoginForm usernameLabel="Name of the user" passwordLabel="Word of the pass" />