Yandex Cloud
Search
Contact UsGet started
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
  • All Services
  • System Status
    • Featured
    • Infrastructure & Network
    • Data Platform
    • Containers
    • Developer tools
    • Serverless
    • Security
    • Monitoring & Resources
    • ML Services
    • Business tools
  • All Solutions
    • By industry
    • By use case
    • Economics and Pricing
    • Security
    • Technical Support
    • Start testing with double trial credits
    • Cloud credits to scale your IT product
    • Gateway to Russia
    • Cloud for Startups
    • Center for Technologies and Society
    • Yandex Cloud Partner program
  • Pricing
  • Customer Stories
  • Documentation
  • Blog
© 2025 Direct Cursus Technology L.L.C.
Yandex SmartCaptcha
  • Getting started
    • All guides
    • Creating a CAPTCHA
    • Deleting a CAPTCHA
    • Getting keys
    • Adding a widget using the advanced method
    • Verifying a CAPTCHA response
    • Viewing operations with resources
  • Access management
  • Pricing policy
  • Terraform reference
  • Monitoring metrics
  • Audit Trails events
  • Release notes

In this article:

  • Adding the SmartCaptcha widget via the advanced method
  • Adding the SmartCaptcha widget that loads whenever required
  • What's next
  1. Step-by-step guides
  2. Adding a widget using the advanced method

Adding the SmartCaptcha widget

Written by
Yandex Cloud
Updated at October 20, 2025
  • Adding the SmartCaptcha widget via the advanced method
  • Adding the SmartCaptcha widget that loads whenever required
  • What's next

Adding the SmartCaptcha widget via the advanced methodAdding the SmartCaptcha widget via the advanced method

You control how the widget loads via the window.smartCaptcha object. This guide uses the onloadFunction callback function for this:

  1. Add the JS script to the user page. Do it by placing the following code anywhere on the page, e.g., inside the <head> tag:

    <script
        src="https://smartcaptcha.yandexcloud.net/captcha.js?render=onload&onload=onloadFunction"
        defer
    ></script>
    
  2. Add to the page an empty container for the widget:

    <div id="<container_ID>"></div>
    

    Where id is a random ID.

  3. Add the code of the callback function to the page:

    <script>
        function onloadFunction() {
        if (window.smartCaptcha) {
            const container = document.getElementById('<container_ID>');
    
            const widgetId = window.smartCaptcha.render(container, {
                sitekey: '<client_key>',
                hl: '<language>',
            });
        }
        }
    </script>
    

    Where:

    • <container_ID>: ID generated at the previous step.
    • sitekey: Client-side key.
    • hl: Widget and task language.

    Consider adding an existence check for the window.smartCaptcha object into the callback function code to avoid error should the function be called before the JS script has finished loading.

    Note

    During the upload, the widget changes the height of its host container to 100px. This might result in an undesirable layout shift on the page due to the height change. To avoid this shift, set the 100px container height before the widget is loaded.

    <div ... style="height: 100px"></div>
    

Adding the SmartCaptcha widget that loads whenever requiredAdding the SmartCaptcha widget that loads whenever required

To add the widget and have your CAPTCHA load whenever required, use the following approach:

window.onloadFunction = () => {
  if (window.smartCaptcha) {
    // Creating a CAPTCHA
  }
}

function handleScriptLoadingError() {
  // Error handling
}

const scriptElement = document.createElement('script');
scriptElement.src = 'https://smartcaptcha.yandexcloud.net/captcha.js?render=onload&onload=onloadFunction';
scriptElement.onerror = handleScriptLoadingError;
document.body.appendChild(scriptElement);

What's nextWhat's next

  • Invisible CAPTCHA.
  • Connecting a CAPTCHA in React.

Was the article helpful?

Previous
Getting keys
Next
Verifying a CAPTCHA response
© 2025 Direct Cursus Technology L.L.C.