Ux Toggle Password Laravel Package

Getting Started

1. Install the package:

   composer require symfony/ux-toggle-password
   

2. Ensure the Stimulus controller is available to your asset pipeline:

   • AssetMapper: confirm @symfony/ux-toggle-password is in importmap.php; run php bin/console importmap:install if needed.
   • Webpack Encore: confirm the package entry exists in assets/controllers.json, then rebuild assets.

   Symfony Flex normally wires this up for you.

3. Confirm the form theme is registered. The package ships a Twig form theme; if your app does not load it automatically, add it to config/packages/twig.yaml:

   twig:
       form_themes:
           - '@UXTogglePassword/form_theme.html.twig'
   

4. Use it in your first form, typically login or registration:

   use Symfony\UX\TogglePassword\Form\TogglePasswordType;
   
   $builder->add('password', TogglePasswordType::class, [
       'label' => 'Password',
   ]);
   

   Render normally with form_row() or form_widget(); do not write custom JavaScript for the basic case.

Where to look first:

• The package README for the exact form type options and template block names.
• vendor/symfony/ux-toggle-password/templates/ to see the form theme and overridable blocks.
• The rendered HTML in devtools: check for the Stimulus data-controller attribute and the toggle button.
• assets/controllers.json or importmap.php if the button does not appear.

Implementation Patterns

• Login form: use the toggle only on the password field; keep the submit button separate. Preserve autocomplete="current-password" on login fields.

• Registration and password reset: apply the toggle to both password and confirmation fields. This is expected behavior and helps users avoid typos.

  $builder
      ->add('plainPassword', TogglePasswordType::class, [
          'label' => 'Password',
          'attr' => ['autocomplete' => 'new-password'],
      ])
      ->add('confirmPassword', TogglePasswordType::class, [
          'label' => 'Confirm password',
          'attr' => ['autocomplete' => 'new-password'],
      ]);
  

• Account/profile screens: use separate toggles for current password, new password, and confirmation. Do not share one toggle across multiple fields unless the package explicitly supports grouping.

• Centralize customization: put labels, icon choices, and button placement into a small form type or form option defaults so every password field behaves consistently. If you need markup changes, override the package’s Twig form theme block in your app’s form theme instead of copying the whole template.

• Turbo and dynamic forms: render password fields normally. Stimulus reconnects after Turbo navigation or form re-rendering, so avoid manual event listeners that assume the field is initialized once. If you swap form fragments manually, make sure the replacement HTML contains the same controller attributes and button markup.

• Accessibility pattern: keep the toggle button keyboard-focusable, keep its accessible label meaningful, and test that screen readers announce the state change. Prefer visible text or a properly labelled icon over an unlabeled icon-only button.

• Progressive enhancement: the password field must remain usable if JavaScript fails. Treat the toggle as an enhancement, not a requirement for submitting the form.

Gotchas and Tips

• No button appears: usually the Stimulus controller is not loaded. Check importmap.php or assets/controllers.json, rebuild assets, clear cache, and inspect the browser console for missing controller errors.

• Custom form theme overrides break the toggle: if your app overrides the password widget block, it may replace the package’s markup. Extend the package form theme or copy the toggle block into your override.

• Wrong button type causes form submits: the toggle must be a button with type="button", not a submit button. The package handles this, but custom Twig overrides can accidentally change it.

• Don’t fight password managers: preserve appropriate autocomplete values such as current-password and new-password. Avoid setting password field values or changing input types outside the package controller.

• Duplicate reveal controls: some browsers provide native password reveal controls. Test your target browsers and avoid adding a third-party reveal widget on top.

• Turbo re-renders: if the toggle stops working after navigation, verify the Stimulus controller is registered globally and that the re-rendered HTML still includes the expected data-controller and button markup.

• Debugging checklist:

  • Inspect the rendered password field for the Stimulus controller attribute.
  • Confirm the toggle button exists and is focusable.
  • Run php bin/console debug:twig to confirm the form theme is active.
  • Run php bin/console debug:asset-map when using AssetMapper.
  • Check assets/controllers.json after package upgrades.

• Styling: target the package’s documented CSS classes or override the form theme block. Avoid relying on generated internal markup, since minor package upgrades may change it.

• Localization: override show/hide labels through form options or translations. Do not hard-code English labels in shared form themes.

• Version pinning: keep the package version aligned with your Symfony UX and Stimulus Bundle versions. After upgrades, re-check the form theme and controller registration if toggles disappear.