BoundField

A Field plus data

Attributes

Attribute	Type	Description
form	`[Form](../forms/form.md?sid=django_forms_forms_form)`	The parent Form instance that this field is bound to.
field	`[Field](../fields/field.md?sid=django_forms_fields_field)`	The Field instance from the form definition that provides validation and widget logic.
name	`string`	The name of the field as defined in the form class.
html_name	`string`	The name attribute used in HTML tags, including any prefixes defined by the form.
html_initial_name	`string`	The name attribute used for the hidden initial value field when tracking changes.
html_initial_id	`string`	The ID attribute used for the hidden initial value field when tracking changes.
label	`string`	The display label for the field, defaulting to a prettified version of the field name if not explicitly set.
help_text	`string`	Additional descriptive text to be displayed alongside the field to guide the user.
renderer	`[BaseRenderer](../renderers/baserenderer.md?sid=django_forms_renderers_baserenderer)`	The engine used to render the field's HTML output, inherited from the parent form.
subwidgets	`list`	A list of BoundWidget instances for fields that produce multiple sub-elements, such as radio buttons or checkboxes.
errors	`[ErrorList](../utils/errorlist.md?sid=django_forms_utils_errorlist)`	Return an ErrorList (empty if there are no errors) for this field.
template_name	`string`	The path to the template used for rendering the field, falling back to the renderer's default if not specified on the field.
data	`any`	Return the data for this BoundField, or None if it wasn't given.
is_hidden	`boolean`	Return True if this BoundField's widget is hidden.
auto_id	`string`	Calculate and return the ID attribute for this BoundField, if the associated Form has specified auto_id.
id_for_label	`string`	Wrapper around the field widget's `id_for_label` method used to determine the 'for' attribute of a label.
initial	`any`	The initial value for the field retrieved from the form's initial data or the field's default.
aria_describedby	`string`	A space-separated string of IDs for help text and error messages to be used in the aria-describedby HTML attribute.
widget_type	`string`	A lowercase string representing the type of widget used by the field, with 'widget' or 'input' suffixes removed.
use_fieldset	`boolean`	Return the value of this BoundField widget's use_fieldset attribute.

Constructor

Signature

def BoundField(
    form: [Form](../forms/form.md?sid=django_forms_forms_form),
    field: [Field](../fields/field.md?sid=django_forms_fields_field),
    name: str
) - > null

Parameters

Name	Type	Description
form	`[Form](../forms/form.md?sid=django_forms_forms_form)`	The form instance this field belongs to.
field	`[Field](../fields/field.md?sid=django_forms_fields_field)`	The field instance being bound.
name	`str`	The name of the field within the form.

Methods

`subwidgets()`

@classmethod
def subwidgets() - > list

Most widgets yield a single subwidget, but others like RadioSelect and CheckboxSelectMultiple produce one subwidget for each choice. This property is cached so that only one database query occurs when rendering ModelChoiceFields.

Returns

Type	Description
`list`	A list of BoundWidget objects representing the individual components of the field's widget.

`errors()`

@classmethod
def errors() - > [ErrorList](../utils/errorlist.md?sid=django_forms_utils_errorlist)

Return an ErrorList (empty if there are no errors) for this field.

Returns

Type	Description
`[ErrorList](../utils/errorlist.md?sid=django_forms_utils_errorlist)`	A collection of error messages associated with this specific field.

`template_name()`

@classmethod
def template_name() - > string

Determines the template path used to render this field, falling back to the renderer's default if not specified on the field.

Returns

Type	Description
`string`	The file path to the template used for rendering.

`get_context()`

@classmethod
def get_context() - > dict

Builds the template context dictionary required to render the field.

Returns

Type	Description
`dict`	A dictionary containing the 'field' instance.

`as_widget()`

@classmethod
def as_widget(
    widget: [Widget](../widgets/widget.md?sid=django_forms_widgets_widget) = null,
    attrs: dict = null,
    only_initial: bool = false
) - > string

Render the field by rendering the passed widget, adding any HTML attributes passed as attrs. If a widget isn't specified, use the field's default widget.

Parameters

Name	Type	Description
widget	`[Widget](../widgets/widget.md?sid=django_forms_widgets_widget)` = null	An optional widget instance to use for rendering instead of the field's default.
attrs	`dict` = null	Additional HTML attributes to apply to the rendered widget tag.
only_initial	`bool` = false	If True, renders the widget using initial data and the initial name prefix.

Returns

Type	Description
`string`	The rendered HTML representation of the widget.

`as_text()`

@classmethod
def as_text(
    attrs: dict = null
) - > string

Return a string of HTML for representing this as an < input type="text" >.

Parameters

Name	Type	Description
attrs	`dict` = null	Additional HTML attributes for the input tag.

Returns

Type	Description
`string`	The HTML string for a text input.

`as_textarea()`

@classmethod
def as_textarea(
    attrs: dict = null
) - > string

Return a string of HTML for representing this as a < textarea >.

Parameters

Name	Type	Description
attrs	`dict` = null	Additional HTML attributes for the textarea tag.

Returns

Type	Description
`string`	The HTML string for a textarea element.

`as_hidden()`

@classmethod
def as_hidden(
    attrs: dict = null
) - > string

Return a string of HTML for representing this as an < input type="hidden" >.

Parameters

Name	Type	Description
attrs	`dict` = null	Additional HTML attributes for the hidden input tag.

Returns

Type	Description
`string`	The HTML string for a hidden input.

`data()`

@classmethod
def data() - > any

Return the data for this BoundField, or None if it wasn't given.

Returns

Type	Description
`any`	The raw data submitted for this field from the form's data source.

`value()`

@classmethod
def value() - > any

Return the value for this BoundField, using the initial value if the form is not bound or the data otherwise.

Returns

Type	Description
`any`	The value to be displayed in the widget, processed for rendering.

`label_tag()`

@classmethod
def label_tag(
    contents: string = null,
    attrs: dict = null,
    label_suffix: string = null,
    tag: string = null
) - > string

Wrap the given contents in a < label >, if the field has an ID attribute. contents should be mark_safe'd to avoid HTML escaping. If contents aren't given, use the field's HTML-escaped label. If attrs are given, use them as HTML attributes on the < label > tag. label_suffix overrides the form's label_suffix.

Parameters

Name	Type	Description
contents	`string` = null	The text to display inside the label; defaults to the field's label.
attrs	`dict` = null	Additional HTML attributes for the label tag.
label_suffix	`string` = null	A string to append to the label text, overriding the default suffix.
tag	`string` = null	The HTML tag to use, such as 'label' or 'legend'.

Returns

Type	Description
`string`	The rendered HTML label or legend tag.

`legend_tag()`

@classmethod
def legend_tag(
    contents: string = null,
    attrs: dict = null,
    label_suffix: string = null
) - > string

Wrap the given contents in a < legend >, if the field has an ID attribute. Contents should be mark_safe'd to avoid HTML escaping. If contents aren't given, use the field's HTML-escaped label. If attrs are given, use them as HTML attributes on the < legend > tag. label_suffix overrides the form's label_suffix.

Parameters

Name	Type	Description
contents	`string` = null	The text to display inside the legend.
attrs	`dict` = null	Additional HTML attributes for the legend tag.
label_suffix	`string` = null	A string to append to the legend text.

Returns

Type	Description
`string`	The rendered HTML legend tag.

`css_classes()`

@classmethod
def css_classes(
    extra_classes: string or list = null
) - > string

Return a string of space-separated CSS classes for this field.

Parameters

Name	Type	Description
extra_classes	`string or list` = null	Additional CSS class names to include in the output.

Returns

Type	Description
`string`	A string containing the combined CSS classes, including error and required classes if applicable.

`is_hidden()`

@classmethod
def is_hidden() - > bool

Return True if this BoundField's widget is hidden.

Returns

Type	Description
`bool`	True if the underlying widget is a hidden type.

`auto_id()`

@classmethod
def auto_id() - > string

Calculate and return the ID attribute for this BoundField, if the associated Form has specified auto_id. Return an empty string otherwise.

Returns

Type	Description
`string`	The generated HTML ID for the field.

`id_for_label()`

@classmethod
def id_for_label() - > string

Wrapper around the field widget's id_for_label method. Useful, for example, for focusing on this field regardless of whether it has a single widget or a MultiWidget.

Returns

Type	Description
`string`	The ID to be used in a < label for="..." > attribute.

`initial()`

@classmethod
def initial() - > any

Retrieves the initial value for the field from the form's initial data or the field's own default.

Returns

Type	Description
`any`	The initial value assigned to this field.

`build_widget_attrs()`

@classmethod
def build_widget_attrs(
    attrs: dict,
    widget: [Widget](../widgets/widget.md?sid=django_forms_widgets_widget) = null
) - > dict

Constructs the dictionary of HTML attributes for the widget, including 'required', 'disabled', and ARIA attributes based on field state.

Parameters

Name	Type	Description
attrs	`dict`	The base HTML attributes to merge with generated attributes.
widget	`[Widget](../widgets/widget.md?sid=django_forms_widgets_widget)` = null	The widget instance for which attributes are being built.

Returns

Type	Description
`dict`	A dictionary of HTML attributes to be applied to the widget.

`aria_describedby()`

@classmethod
def aria_describedby() - > string

Generates the ID strings for help text and errors to be used in the aria-describedby attribute for accessibility.

Returns

Type	Description
`string`	A space-separated string of IDs, or an empty string if none apply.

`widget_type()`

@classmethod
def widget_type() - > string

Returns a simplified string representation of the widget's class name (e.g., 'text' for 'TextInput').

Returns

Type	Description
`string`	The lowercase name of the widget type.

`use_fieldset()`

@classmethod
def use_fieldset() - > bool

Return the value of this BoundField widget's use_fieldset attribute.

Returns

Type	Description
`bool`	True if the widget should be grouped in a fieldset.

Attributes​

Constructor​

Signature​

Parameters​

Methods​

subwidgets()​

Returns​

errors()​

Returns​

template_name()​

Returns​

get_context()​

Returns​

as_widget()​

Parameters​

Returns​

as_text()​

Parameters​

Returns​

as_textarea()​

Parameters​

Returns​

as_hidden()​

Parameters​

Returns​

data()​

Returns​

value()​

Returns​

label_tag()​

Parameters​

Returns​

legend_tag()​

Parameters​

Returns​

css_classes()​

Parameters​

Returns​

is_hidden()​

Returns​

auto_id()​

Returns​

id_for_label()​

Returns​

initial()​

Returns​

build_widget_attrs()​

Parameters​

Returns​

aria_describedby()​

Returns​

widget_type()​

Returns​

use_fieldset()​

Returns​

Attributes

Constructor

Signature

Parameters

Methods

`subwidgets()`

Returns

`errors()`

Returns

`template_name()`

Returns

`get_context()`

Returns

`as_widget()`

Parameters

Returns

`as_text()`

Parameters

Returns

`as_textarea()`

Parameters

Returns

`as_hidden()`

Parameters

Returns

`data()`

Returns

`value()`

Returns

`label_tag()`

Parameters

Returns

`legend_tag()`

Parameters

Returns

`css_classes()`

Parameters

Returns

`is_hidden()`

Returns

`auto_id()`

Returns

`id_for_label()`

Returns

`initial()`

Returns

`build_widget_attrs()`

Parameters

Returns

`aria_describedby()`

Returns

`widget_type()`

Returns

`use_fieldset()`

Returns