FR(Docs): Suggested updates to the Authenticator Documentation

[reesscot]

Copied from this comment: #1497 (comment)

On which framework/platform would you like to see this feature implemented?

React, React Native

Which UI component is this feature-request for?

Authenticator

Please describe your feature-request in detail.

@calebpollman

Generally, the documentation is good, but since time has changed the capabilities it seems like it is a bit dated.

I'm using React Native but this approach also works with React or JavaScript.

Firstly, the documentation relies on examples. There isn't the classic documentation style that outlines each property, class or method that is available on each hook or module. This would already be helpful and probably easier to maintain. When something is deprecated the page that the information is displayed can also say it has been deprecated. This is relatively common when reviewing documentation for other APIs.

Secondly, currently the AWS Amplify customization docs suggest this approach but this is not quite right because the NBM "module itself seems to handle the revealing of the children (see my earlier post's "Other finds" section).

Lastly, if you search for "handlesubmit" on the authenticator documentation page the word doesn't exist

It would at the bare minimum be helpful to know that this exists as a prop when instantiating a custom "Sign In" view.

For an example, you can go with the a basic approach, which satisfies almost all use-cases.

Use case: I want to add custom authentication to my app.
Result:

Provider

<Authenticator.Provider>
  <Authenticator
    components={{
      SignIn: props => {
        return <MySignIn {...props} />;
      },
      SignUp: props => {
        return <MySignUp {...props} />;
      },
    }}
    Header={MyHeader}
    Footer={Footer}
  >
    {children}
  </Authenticator>
</Authenticator.Provider>

MySignIn component

const MySignIn: React.FC<any> = ({ toSignUp, handleSubmit }) => {
  const [username, setUsername] = useState('');
  const [password, setPassword] = useState('');

  const handleSignIn = async () => {
    try {
      await handleSubmit({ username, password });
    } catch (error) {
      console.error('Error signing in:', error);
    }
  };
  return (
    <View
      style={{
        marginTop: 24,
        padding: 24,
      }}
    >
      <TextInterBold style={[Styles.h2, { marginBottom: 30 }]}>
        Sign in
      </TextInterBold>
      <View
        style={{
          marginBottom: 30,
        }}
      >
        <Input
          style={Styles.input}
          placeholder="Username"
          onChangeText={text => setUsername(text)}
          value={username}
          autoComplete="email"
        />
        <Input
          style={Styles.input}
          placeholder="Password"
          secureTextEntry={true}
          onChangeText={text => setPassword(text)}
          value={password}
          autoComplete="password"
        />
      </View>
      <View
        style={{
          flexDirection: 'row',
          justifyContent: 'space-between',
          marginTop: 10,
          marginBottom: 30,
        }}
      >
        <Button
          style={[Styles.button, { width: '25%' }]}
          onPress={handleSignIn}
        >
          Sign In
        </Button>
        <Button style={[Styles.button, { width: '25%' }]} onPress={toSignUp}>
          Create an account
        </Button>
      </View>
    </View>
  );
};

export default MySignIn;

Note the use of handleSubmit versus what the documentation suggests with is signIn()

You can see the documentation suggests using signIn() here. and in several other places for JavaScript or React. This is misleading as we both know that this doesn't work as expected.

I would suggest including information at this point in the documentation that explains the use of handleSubmit, even if this is a temporary alternative and a fix is coming in the future. Because for people like myself I almost had to forego using AWS Amplify due to the lack of ability to log a user in with a custom form. That is probably not ideal for AWS Amplify.

I hope this helps and wish you luck improving the docs. Thanks!

Please describe a solution you'd like.

No response

We love contributors! Is this something you'd be interested in working on?

• 👋 I may be able to implement this feature request.
• ⚠️ This feature might incur a breaking change.