diff --git a/packages/amplify_authenticator/lib/src/widgets/form_fields/confirm_sign_up_form_field.dart b/packages/amplify_authenticator/lib/src/widgets/form_fields/confirm_sign_up_form_field.dart
index 2b7ef794fd9..07411d94b4b 100644
--- a/packages/amplify_authenticator/lib/src/widgets/form_fields/confirm_sign_up_form_field.dart
+++ b/packages/amplify_authenticator/lib/src/widgets/form_fields/confirm_sign_up_form_field.dart
@@ -43,7 +43,7 @@ abstract class ConfirmSignUpFormField<FieldValue>
           validator: validator,
         );
 
-  /// Creates a username component.
+  /// {@macro amplify_authenticator.username_form_field}
   static ConfirmSignUpFormField username({
     Key? key,
     FormFieldValidator<UsernameInput>? validator,
diff --git a/packages/amplify_authenticator/lib/src/widgets/form_fields/sign_in_form_field.dart b/packages/amplify_authenticator/lib/src/widgets/form_fields/sign_in_form_field.dart
index 2ec6c402f74..da3ee93ae37 100644
--- a/packages/amplify_authenticator/lib/src/widgets/form_fields/sign_in_form_field.dart
+++ b/packages/amplify_authenticator/lib/src/widgets/form_fields/sign_in_form_field.dart
@@ -48,7 +48,7 @@ abstract class SignInFormField<FieldValue> extends AuthenticatorFormField<
           requiredOverride: required,
         );
 
-  /// Creates a username FormField for the sign in step.
+  /// {@macro amplify_authenticator.username_form_field}
   static SignInFormField username({
     Key? key,
     FormFieldValidator<UsernameInput>? validator,
diff --git a/packages/amplify_authenticator/lib/src/widgets/form_fields/sign_up_form_field.dart b/packages/amplify_authenticator/lib/src/widgets/form_fields/sign_up_form_field.dart
index 1bb6cb8742f..b7d5cea06d2 100644
--- a/packages/amplify_authenticator/lib/src/widgets/form_fields/sign_up_form_field.dart
+++ b/packages/amplify_authenticator/lib/src/widgets/form_fields/sign_up_form_field.dart
@@ -46,7 +46,16 @@ abstract class SignUpFormField<FieldValue> extends AuthenticatorFormField<
           requiredOverride: required,
         );
 
-  /// Creates a username component.
+  /// {@template amplify_authenticator.username_form_field}
+  /// Creates a username component based on your app's configuration.
+  ///
+  /// The look and behavior of this widget will depend on your app's auth configuration.
+  /// The `usernameAttributes` will be used to determine if the field is a standard
+  /// username field, and email field, or a phone number field.
+  /// {@endtemplate}
+  ///
+  /// If your app is configured to use email or phone, the value provided for this widget
+  /// will be saved as the user's email or phone number in addition to their username.
   static SignUpFormField username({
     Key? key,
     FormFieldValidator<UsernameInput>? validator,