Verification Code / OTP

Displays a set of input fields to accept a verification code from a user. It is common place on websites these days to send verification codes via email or mobile. These codes range from four to six digits. The default number of digits displayed by the component is four (4). In this documentation, we may interchange the words PIN, PIN code and verification code. We mean the same thing.

        
            <x-bladewind::code  />
        
    

        
            <x-bladewind::code size="big"  />
        
    

The verification code component allows you to specify how many boxes you want to display by specifying the total_digits attribute. There is no restriction on the maximum value you can specify. In a finance app, you could use this to collect account numbers.

        
            <x-bladewind::code total_digits="5"  />
        
    

If you don't want the code being entered to be visible, set the mask="true" attribute.

        
            <x-bladewind::code mask="true"  />
        
    

Access the Verification Code

What happens after the user enters their verification code? The component creates a hidden input field with the name that was passed as the name attribute.

            
                <x-bladewind::code name="pin_code"  />
            
        

The above will create the input fields for the verification codes and create the hidden input below

            
                <input type="hidden" name="pin_code" class="pin_code ..." id="pin_code"  />
            
        

You can access the value of pin_code either via Javascript or via PHP if you intend to post it in a form to your backend. The on_verify attribute allows you to specify a function that should be called when the user has entered a value into the last verification code field. This should just be the function name without parentheses and parameters. If you wish to call verifyPin() after the user enters the code, just type on_verify="verifyPin". The component passes the code entered by the user to your function, as well as the name of the component, so, your function declaration needs to expect one or two parameters. Still using the verifyPin example, your function declaration will be:

            
                // NOTE: this is not a Bladewind helper function
                // it should be a function in your project

                verifyPin = (code, name) => {

                    // do something here with the code
                }
            
        

Let's consider a practical example. Enter any code in the fields below and get notified of the code you entered.

            
                <x-bladewind::code on_verify="checkPin" />

                <script>
                    checkPin = (code) => {
                        alert(`You entered: ${code}`);
                    }
                </script>
            
        

Clear PIN/Code

There are cases where you will want to clear the verification code input field probably because the user entered a wrong pin and you want them to try entering the pin again. Also, in an SPA app where you probably popup a screen for users to enter a code before performing an action, the last entered may still be in the fields. clearPin(name) is a Bladewind helper function that easily lets you reset your verification codes. The example below expects the code 2024

            
                <x-bladewind::code name="clear_me" on_verify="checkPinAndClear" />
            
        

            
                <script>
                    checkPinAndClear = (code) => {
                        if(code !== 2024) {
                            clearPin('clear_me');
                            showNotification('Wrong Code', 'Please enter your code again', 'error');
                        }
                    }
                </script>
            
        

Displaying Errors

The verification code component comes with a hidden field that has the error message to display when validation fails for the code the user entered. To allow for translatable messages, the error message is defined on the component using the error_message attribute.

The example below expects 2024 as the code.

    <x-bladewind::code
        name="pcode"
        error_message="Yoh! check your code"
        on_verify="checkPinShowError" />

        
            <script>
                checkPinShowError = (code) => {
                    if( code !== 2024) {
                        clearPin('pcode');
                        showPinError('pcode');
                    }
                }
            </script>
        
    

The error message is displayed by invoking the Javascript helper function showPinError(name). It accepts the name provided to the code component as a parameter. The error message is automatically hidden by calling the hidePinError(name) Javascript helper function. The second parameter to this function is what controls the automatic hiding of the error message. If you do not want to automatically close the error message, set the parameter to false.

        
            <script>
                checkPinShowError = (code) => {
                    ...
                    // the error message will not hide after 10 seconds
                    showPinError('pcode', false);
                    ...
                }
            </script>
        
    

Show the Spinner

The verification code component comes with a hidden spinner that can be made visible by invoking the showSpinner(name) Javascript helper function. It accepts the name provided to the code component as a parameter. The verification code spinner can be useful if your verification is done via an ajax call to an API that may take a second or two. Showing the spinner will let the user know you are performing an action.

        
            <x-bladewind::code name="spin_me" on_verify="validatePin"  />
        
    

        
            <script>
                validatePin = (code, name) => {
                    showSpinner(name);
                    ajaxCall('/verify/pin', `code=${code}`, ...
                }
            </script>
        
    

Since Bladewind does not know how long your Ajax call might take or when your process is complete, it cannot automatically hide the spinner for you. You can do that by calling hideSpinner(name), where name is the name of your verification code field.

        
            <script>
                ...
                hideSpinner('spin_me');
                ...
            </script>
        
    

Show Success Icon

The verification code component also comes with a hidden checkmark to show when a pin is valid. This can be invoked using the showPinSuccess(name) Javascript helper function. It accepts the name provided to the code component as a parameter. In the example below, the spinner shows after the code is entered and disappears to give way to the checkmark after 5 seconds.

        
            <x-bladewind::code name="spin_me_yes" on_verify="spinAndSucceed"  />
        
    

    <script>
        spinAndSucceed = (code, name) => {
            showSpinner(name);
            setTimeout( () => { showPinSuccess(name); }, 5000);
        }
    </script>

Countdown To Resend Code

This can be useful for two scenarios. The user never received the code you sent so they will need to request another. The user received a code that somehow does not seem to work and will need to request for a new one. Specifying a value for the timer attribute automatically shows a countdown timer. The attributes accepts number of seconds to countdown to.

Bladewind expects you to have an HTML element on your page with class="bw-code-timer-done". Ideally this should be hidden. The innerHTML (content) of that element is what will be displayed when the timer is done. This approach provides you the flexibility of handling your code resend anyway you want.

        
            <x-bladewind::code name="time_me" timer="30"  />
        
    

        
            <!-- the DIV that contains the content to display when timer is done -->

            <div class="bw-code-timer-done hidden">
                <x-bladewind.button
                    name="send-code"
                    size="tiny"
                    type="secondary"
                    has_spinner="true"
                    onclick="sendNewCode()">
                    send me another code
                </x-bladewind.button>
            </div>
        
    

    <script>
        sendNewCode = () => {
           showButtonSpinner('.bw-time_me-timer .done .send-code');
           setTimeout( () => {
               showNotification('Code Sent','Please check your email or SMS for a new verification code');
                hideButtonSpinner('.bw-time_me-pin-timer .done .send-code');
                hide('.bw-time_me-pin-timer .done .send-code')
                setFocus('time_me');
                clearTimeout();
           }, 5000);
        }
    </script>

Once the countdown is done, the content of your bw-code-timer-done DIV is copied into a DIV that can be accessed using the class .bw-[name-of-code-field]-pin-timer .done. From our above example, our resend code content will be copied into a DIV accessible with .bw-time_me-pin-timer .done. That is how come our showButtonSpinner() line was targeting the button at .bw-time_me-pin-timer .done .send-code.

Manually Trigger the Timer

There are cases where you may want to manually trigger the timer. For example, you first want the user to have at least entered the code wrongly once or twice before you trigger a countdown. You can do this by calling the showTimer(name, duration) helper function. The example below expects 2024 as the code. Enter it wrongly two times to trigger the timer.

        
            <x-bladewind::code name="trigger_me" on_verify="triggerTimerManually"  />
        
    

let attempts = 0;
triggerTimerManually = (code, name) => {
    if(parseInt(code) !== 2024) {
        attempts++
        showPinError(name);
        clearPin(name);
    }
    if(attempts >= 2) showTimer(name, 15);
}

Full List Of Attributes

The table below shows a comprehensive list of all the attributes available for the Spinner component.

Verification Code with all attributes defined

    <x-bladewind::code
        name="pin-code"
        total_digits="5"
        on_verify="verifyPin"
        has_spinner="false"
        mask="false"
        timer="15"
        error_message="please enter the correct code"  />