0
# reCAPTCHA Widgets
1

2
Widget implementations for different reCAPTCHA types, providing various user interaction patterns and security models. All widgets extend the base `ReCaptchaBase` class and integrate with Django's widget system for form rendering.
3

4
## Capabilities
5

6
### ReCaptchaBase
7

8
Base widget class providing common functionality for all reCAPTCHA widget types. Handles UUID generation, CSS class management, template context building, and data attribute configuration.
9

10
```python { .api }
11
class ReCaptchaBase(widgets.Widget):
12
    """
13
    Base widget for Google reCAPTCHA integration.
14
    
15
    Provides common functionality for all reCAPTCHA widget types.
16
    """
17
    
18
    recaptcha_response_name = "g-recaptcha-response"
19
    
20
    def __init__(self, api_params=None, *args, **kwargs):
21
        """
22
        Initialize base reCAPTCHA widget.
23
        
24
        Parameters:
25
        - api_params (dict, optional): Additional API parameters for reCAPTCHA
26
        - **kwargs: Standard Django widget parameters
27
        """
28
    
29
    def value_from_datadict(self, data, files, name):
30
        """
31
        Extract reCAPTCHA response value from form data.
32
        
33
        Parameters:
34
        - data (dict): Form data dictionary
35
        - files (dict): Form files dictionary  
36
        - name (str): Field name
37
        
38
        Returns:
39
        str | None: reCAPTCHA response token or None
40
        """
41
    
42
    def get_context(self, name, value, attrs):
43
        """
44
        Build template context for widget rendering.
45
        
46
        Parameters:
47
        - name (str): Field name
48
        - value: Field value
49
        - attrs (dict): Widget attributes
50
        
51
        Returns:
52
        dict: Template context including public_key, widget_uuid, api_params, recaptcha_domain
53
        """
54
    
55
    def build_attrs(self, base_attrs, extra_attrs=None):
56
        """
57
        Build widget HTML attributes.
58
        
59
        Parameters:
60
        - base_attrs (dict): Base attributes
61
        - extra_attrs (dict, optional): Additional attributes
62
        
63
        Returns:
64
        dict: Complete widget attributes including data-widget-uuid, data-callback, data-size
65
        """
66
```
67

68
### ReCaptchaV2Checkbox
69

70
Standard reCAPTCHA V2 checkbox widget that displays the familiar "I'm not a robot" checkbox interface. Users must click the checkbox and may need to complete additional challenges.
71

72
```python { .api }
73
class ReCaptchaV2Checkbox(ReCaptchaBase):
74
    """
75
    reCAPTCHA V2 Checkbox widget.
76
    
77
    Displays standard checkbox interface requiring user interaction.
78
    """
79
    
80
    input_type = "hidden"
81
    template_name = "django_recaptcha/widget_v2_checkbox.html"
82
```
83

84
### ReCaptchaV2Invisible
85

86
reCAPTCHA V2 Invisible widget that runs in the background without displaying a visible checkbox. Automatically triggers on form submission and may show challenges for suspicious traffic.
87

88
```python { .api }
89
class ReCaptchaV2Invisible(ReCaptchaBase):
90
    """
91
    reCAPTCHA V2 Invisible widget.
92
    
93
    Runs invisibly in background, showing challenges only when needed.
94
    """
95
    
96
    input_type = "hidden"
97
    template_name = "django_recaptcha/widget_v2_invisible.html"
98
    
99
    def build_attrs(self, base_attrs, extra_attrs=None):
100
        """
101
        Build attributes with forced invisible size.
102
        
103
        Overrides data-size to "invisible" regardless of input.
104
        """
105
```
106

107
### ReCaptchaV3
108

109
reCAPTCHA V3 widget that provides score-based validation without user interaction. Analyzes user behavior and returns a score (0.0-1.0) indicating likelihood of being human.
110

111
```python { .api }
112
class ReCaptchaV3(ReCaptchaBase):
113
    """
114
    reCAPTCHA V3 widget with score-based validation.
115
    
116
    Provides frictionless experience with risk analysis scoring.
117
    """
118
    
119
    input_type = "hidden"
120
    template_name = "django_recaptcha/widget_v3.html"
121
    
122
    def __init__(self, api_params=None, action=None, required_score=None, *args, **kwargs):
123
        """
124
        Initialize reCAPTCHA V3 widget.
125
        
126
        Parameters:
127
        - api_params (dict, optional): Additional API parameters
128
        - action (str, optional): Action name for analytics and validation
129
        - required_score (float, optional): Minimum required score (0.0-1.0).
130
          Defaults to RECAPTCHA_REQUIRED_SCORE setting.
131
        - **kwargs: Standard widget parameters
132
        """
133
    
134
    def value_from_datadict(self, data, files, name):
135
        """
136
        Extract V3 response token from form data.
137
        
138
        Uses field name instead of standard g-recaptcha-response.
139
        """
140
    
141
    def get_context(self, name, value, attrs):
142
        """
143
        Build template context including action parameter.
144
        
145
        Returns:
146
        dict: Context with action added for V3 template rendering
147
        """
148
```
149

150
## Widget Configuration
151

152
### API Parameters
153

154
All widgets accept `api_params` dictionary for additional reCAPTCHA configuration:
155

156
```python
157
widget = ReCaptchaV2Checkbox(api_params={
158
    'hl': 'es',  # Language
159
    'theme': 'dark',  # Theme
160
    'size': 'compact'  # Size
161
})
162
```
163

164
### Data Attributes
165

166
Widgets support customization through HTML data attributes:
167

168
- `data-callback`: JavaScript callback function name
169
- `data-size`: Widget size ('normal', 'compact', 'invisible')
170
- `data-theme`: Color theme ('light', 'dark')
171
- `data-sitekey`: Automatically set to public key
172

173
### Template Customization
174

175
Each widget uses Django templates that can be overridden:
176

177
- `django_recaptcha/widget_v2_checkbox.html`
178
- `django_recaptcha/widget_v2_invisible.html`  
179
- `django_recaptcha/widget_v3.html`
180

181
## Usage Examples
182

183
### Basic Widget Usage
184

185
```python
186
from django import forms
187
from django_recaptcha.fields import ReCaptchaField
188
from django_recaptcha.widgets import ReCaptchaV2Checkbox
189

190
class MyForm(forms.Form):
191
    captcha = ReCaptchaField(widget=ReCaptchaV2Checkbox())
192
```
193

194
### V2 Invisible Widget
195

196
```python
197
from django_recaptcha.widgets import ReCaptchaV2Invisible
198

199
class ContactForm(forms.Form):
200
    name = forms.CharField()
201
    email = forms.EmailField()
202
    captcha = ReCaptchaField(widget=ReCaptchaV2Invisible())
203
```
204

205
### V3 Widget with Score Validation
206

207
```python
208
from django_recaptcha.widgets import ReCaptchaV3
209

210
class LoginForm(forms.Form):
211
    username = forms.CharField()
212
    password = forms.CharField(widget=forms.PasswordInput)
213
    captcha = ReCaptchaField(
214
        widget=ReCaptchaV3(
215
            action='login',
216
            required_score=0.7
217
        )
218
    )
219
```
220

221
### Custom Styling
222

223
```python
224
class StyledForm(forms.Form):
225
    captcha = ReCaptchaField(
226
        widget=ReCaptchaV2Checkbox(
227
            api_params={'theme': 'dark', 'size': 'compact'},
228
            attrs={
229
                'data-callback': 'onCaptchaSuccess',
230
                'class': 'custom-recaptcha'
231
            }
232
        )
233
    )
234
```
235

236
### Multi-language Support
237

238
```python
239
class MultiLangForm(forms.Form):
240
    captcha = ReCaptchaField(
241
        widget=ReCaptchaV2Checkbox(
242
            api_params={'hl': 'fr'}  # French language
243
        )
244
    )
245
```