Inputs¶

GOV.UK Design System form input components including TextInput, Textarea, Select, Checkboxes, Radios etc.

These components are subclasses of Field which provides common functionality like rendering labels, hints, errors, setting values, and validating required fields.

fast_gov_uk.design_system.inputs.Label(field_id: str, text: str, heading: str = '', required: bool = True, extra_cls: str = '') → FT¶

Used by the Field component to render a label.

Handles whether the label is a heading, whether the field is required etc.

Use this if you are creating a custom field.

Parameters:

field_id (str) – HTML id of the field this label is for.
text (str) – Text to be displayed in the label.
heading (str, optional) – Heading size. Defaults to “”.
required (bool, optional) – Is this for a field that is required? Defaults to True.
extra_cls (str, optional) – Extra CSS classes. Defaults to “”.

Returns:

A FastHTML label component.

Return type:

FT

fast_gov_uk.design_system.inputs.Hint(field_id: str, text: str, extra_cls: str = '') → FT¶

Used by the Field component to render a hint.

Use this if you are creating a custom field.

Parameters:

field_id (str) – HTML id of the field this hint is for.
text (str) – Text to be displayed as hint.
extra_cls (str, optional) – Extra CSS classes. Defaults to “”.

Returns:

A FastHTML hint component.

Return type:

FT

fast_gov_uk.design_system.inputs.Error(field_id: str, text: str, extra_cls: str = '') → FT¶

Used by the Field component to render error message.

Use this if you are creating a custom field.

Parameters:

field_id (str) – HTML id of the field this error is for.
text (str) – Text to be displayed as error.
extra_cls (str, optional) – Extra CSS classes. Defaults to “”.

Returns:

A FastHTML error component.

Return type:

FT

class fast_gov_uk.design_system.inputs.AbstractField¶

Bases: object

Every form field is a subclass of this type.

This is useful when e.g. we are having to distinguish fields in a form that contains fields as well as non-field elements like H1 and P.

These types of mixed forms are quite common in question pages.

class fast_gov_uk.design_system.inputs.Field(name: str, label: str = '', hint: str = '', error: str = '', heading: str = '', required: bool = True, **kwargs)¶

Bases: AbstractField

Baseclass for form inputs. Provides scaffolding for -

rendering labels

rendering hints

rendering errors

setting field values

validation for required fields

If you are want to implement a custom GOV.UK input, this is a good base class to inherit from.

Parameters:

name (str) – The name of the field.
label (str, optional) – Label for the field. Defaults to “”.
hint (str, optional) – Hint for the field. Defaults to “”.
error (str, optional) – Error message for the field. Defaults to “”.
heading (str, optional) – Heading size. Defaults to “”.
required (bool, optional) – Is this field required? Defaults to True.
**kwargs – Additional keyword arguments.

property clean¶: Get “clean” data from a field when a form is being processed by a form Backend.

property annotations¶

Returns label, hint, and error components for the field.

Returns:: (Label, Hint, Error)
Return type:: tuple

class fast_gov_uk.design_system.inputs.Select(*args, choices: dict | None = None, **kwargs)¶

Bases: Field

GOV.UK Select component. Renders a dropdown. Inherits from Field.

This component should only be used as a last resort in public-facing services because research shows that some users find selects very difficult to use.

Use Checkbox or Radio components instead.

Examples

>>> ds.Select("question", choices={"yes": "Yes", "no": "No"})
# Renders a dropdown select with the given options - "Yes" and "No.
# Note the values for these options are "yes" and "no" respectively

Parameters:

*args – Arguments for Field.
choices (dict, optional) – Choices for the select. Defaults to None.
**kwargs – Additional keyword arguments.

property clean¶: Get “clean” data from a field when a form is being processed by a form Backend.

property options¶: Convert the choices dict into a list of <option> to be inserted into the Select component.

class fast_gov_uk.design_system.inputs.Textarea(*args, rows: int = 5, **kwargs)¶

Bases: Field

GOV.UK Textarea component. Inherits from Field.

Use this component when you need to let users enter more than a single line of text.

Examples

>>> ds.Textarea('test')
# Renders a text area with the default 5 rows

Parameters:

*args – Arguments for Field.
rows (int, optional) – Number of rows in the textarea. Defaults to 5.
**kwargs – Additional keyword arguments.

class fast_gov_uk.design_system.inputs.PasswordInput(*args, **kwargs)¶

Bases: Field

GOV.UK Password input component. Inherits from Field.

Use this component when you need users to type a password.

Examples

>>> ds.PasswordInput('test')
# Renders a password input

Parameters:

*args – Arguments for Field.
**kwargs – Additional keyword arguments.

property input¶: Input part for this component.

property button¶: Button part for this component

class fast_gov_uk.design_system.inputs.CharacterCount(*args, rows: int = 5, maxchars: int | None = None, maxwords: int | None = None, threshold: int | None = None, **kwargs)¶

Bases: Field

GOV.UK Character count component. Renders a Textarea with a character/word count message.

Help users know how much text they can enter when there is a limit on the number of characters.

It is recommended to always test your service without a character count first and to only use the character count component when there is a good reason for limiting the number of characters users can enter.

Examples

>>> ds.CharacterCount('test')
# Renders a text area
>>> ds.CharacterCount('test', maxchars=100)
# Renders a text area with a limit of 100 characters max
>>> ds.CharacterCount('test', maxwords=10)
# Renders a text area with a limit of 10 words max
>>> ds.CharacterCount('test', maxwords=10, threshold=50)
# Renders a text area with a limit of 10 words max but the message that says
# "You have X words left" only appears after 50% of the limit is crossed.

Parameters:

*args – Arguments for Field.
rows (int, optional) – Number of rows in the textarea. Defaults to 5.
maxchars (int, optional) – Max characters allowed. Defaults to None.
maxwords (int, optional) – Max words allowed. Defaults to None.
threshold (int, optional) – Threshold percent for showing count message. Defaults to None.
**kwargs – Additional keyword arguments.

property textarea¶: Textarea part of CharacterCount.

property message¶: Message part of CharacterCount.

class fast_gov_uk.design_system.inputs.InputWidth(*values)¶

Bases: Enum

Enum to define GOV.UK supported input widths to be passed into TextInput as width param.

class fast_gov_uk.design_system.inputs.TextInput(*args, width: InputWidth = InputWidth.DEFAULT, prefix: str = '', suffix: str = '', autocomplete: str = '', numeric: bool = False, spellcheck: bool = False, extra_spacing: bool = False, **kwargs)¶

Bases: Field

GOV.UK Text Input component. Inherits from Field.

Use the text input component when you need to let users enter text that is no longer than a single line, such as their name or email address.

Examples

>>> ds.TextInput('test')
# Renders a standard text input
>>> ds.TextInput('test', width=InputWidth.W50)
# Renders a text input with a width of 50%
>>> ds.TextInput('test', prefix="£")
# Renders a text input with a prefix of "£"
>>> ds.TextInput('test', suffix="%")
# Renders a text input with a suffix of "%"
>>> ds.TextInput('test', autocomplete="postal-code")
# Renders a text input that uses the autocomplete features in
# modern browsers to fill-in the postcode
>>> ds.TextInput('test', numeric=True)
# Renders a text input that uses the numeric keypad on devices
# with on-screen keyboards.
>>> ds.TextInput('test', spellcheck=True)
# Renders a text input with the spellcheck turned on
>>> ds.TextInput('test', extraspacing=True)
# Renders a text input with extra spacing

Parameters:

*args – Arguments for Field.
width (InputWidth, optional) – Width of TextInput. Defaults to InputWidth.DEFAULT.
prefix (str, optional) – Prefix to TextInput. Defaults to “”.
suffix (str, optional) – Suffix to TextInput. Defaults to “”.
autocomplete (str, optional) – Autocomplete value. Defaults to “”.
numeric (bool, optional) – Is TextInput numeric? Defaults to False.
spellcheck (bool, optional) – Enable spellcheck. Defaults to False.
extra_spacing (bool, optional) – Extra letter spacing. Defaults to False.
**kwargs – Additional keyword arguments.

property input¶: Input part of this component.

class fast_gov_uk.design_system.inputs.Checkbox(name: str, value: str, label: str, hint: str = '', checked: bool = False, exclusive: bool = False, **kwargs)¶

Bases: AbstractField

Checkbox component. Used to define individual checkboxes to be passed into the Checkboxes component.

Note that this inherits from AbstractField instead of Field because it is only meant to be used inside the Checkboxes component - which inherits from Field.

Examples

>>> cb = ds.Checkbox('test', 'test', 'Test Label')
# Renders a Checkbox called "test" with a label "Test Label"
>>> cb = ds.Checkbox('test', 'test', 'Test Label', checked=True)
# Renders the same Checkbox but its checked by default
>>> cb = ds.Checkbox('test', 'test', 'Test Label', checked=True)
# Renders the same Checkbox but its checked by default
>>> cb = ds.Checkbox('test', 'test', 'Test Label', exclusive=True)
# Renders the same Checkbox when this checkbox it clicked, it unchecks all other
# checkboxes - handy for options like "None of the above"

Parameters:

name (str) – The name of the checkbox element.
value (str) – The value of the checkbox element.
label (str) – Label for the checkbox element.
hint (str, optional) – Hint for the checkbox element. Defaults to “”.
checked (bool, optional) – Make this checkbox checked. Defaults to False.
exclusive (bool, optional) – Make this checkbox exclusive. Defaults to False.
**kwargs – Additional keyword arguments.

property label_component¶: Label component.

property hint_component¶: Hint component.

class fast_gov_uk.design_system.inputs.Checkboxes(*args, checkboxes: List[Checkbox] | None = None, choices: dict | None = None, small: bool = False, **kwargs)¶

Bases: Field

GOV.UK Checkboxes component. Let users select one or more options by using the checkboxes component.

Use the checkboxes component when you need to help users: select multiple options from a list or to toggle a single option on or off.

Use the handy “choices” parameter as a shortcut to quickly define standard checkbox groups.

Examples

>>> ds.Checkboxes("question", choices={"yes": "Yes!", "no": "Maybe later.."})
# Renders checkboxes called "question" with values "yes" and "no" with texts
# "Yes!" and "Maybe later.." respectively
>>> ds.Checkboxes("question", choices={"yes": "Yes!", "no": "Maybe later.."}, small=True)
# Renders the same checkbox with more compact styling
>>> cb_yes = ds.Checkbox("question", "yes", "Yes!")
>>> cb_no = ds.Checkbox("question", "no", "Maybe later..")
>>> ds.Checkboxes("question", cb_yes, cb_no)
# Renders the same checkboxes but by defining individual components, we can use
# all of the underlying configurations

Parameters:

*args – Arguments for Field.
checkboxes (List[Checkbox], optional) – List of Checkbox components.
choices (dict, optional) – Shorthand for simple checkboxes.
small (bool, optional) – Renders small Checkboxes. Defaults to False.
**kwargs – Additional keyword arguments.

property clean¶: Get “clean” data from a field when a form is being processed by a form Backend.

make_checkboxes()¶: Make checkboxes from choices.

class fast_gov_uk.design_system.inputs.Radio(name: str, value: str, label: str, hint: str = '', checked: bool = False, reveal: Field | None = None, **kwargs)¶

Bases: AbstractField

Radio component. Used to define individual radioes to be passed into the Radios component.

Note that this inherits from AbstractField instead of Field because it is only meant to be used inside the Radios component - which inherits from Field.

Examples

>>> cb = ds.Radio('test', 'test', 'Test Label')
# Renders a radio called "test" with a label "Test Label"
>>> cb = ds.Radio('test', 'test', 'Test Label', checked=True)
# Renders the same radio but its checked by default
>>> cb = ds.Radio('test', 'test', 'Test Label', checked=True)
# Renders the same radio but its checked by default

Parameters:

name (str) – The name of the radio element.
value (str) – The value of the radio element.
label (str) – Label for the radio element.
hint (str, optional) – Hint for the radio element. Defaults to “”.
checked (bool, optional) – Make this radio checked. Defaults to False.
reveal (Field, optional) – Field revealed when Radio is selected. Defaults to None.
**kwargs – Additional keyword arguments.

property label_component¶: Label component.

property hint_component¶: Hint component.

property data_aria_controls¶: Aria-controls component.

property base_radio¶: Base radio component.

class fast_gov_uk.design_system.inputs.Radios(*args, radios: List[Radio] | None = None, choices: dict | None = None, small: bool = False, inline: bool = False, **kwargs)¶

Bases: Field

GOV.UK Radios component. Use the radios component when users can only select one option from a list.

Use the handy “choices” parameter as a shortcut to quickly define standard radio groups.

Examples

>>> ds.Radios("question", choices={"yes": "Yes!", "no": "Maybe later.."})
# Renders radios called "question" with values "yes" and "no" with texts
# "Yes!" and "Maybe later.." respectively
>>> ds.Radios("question", choices={"yes": "Yes!", "no": "Maybe later.."}, small=True)
# Renders the same checkbox with more compact styling
>>> ds.Radios("question", choices={"yes": "Yes!", "no": "Maybe later.."}, inline=True)
# Renders the same checkbox with inline styling
>>> yes = ds.Radio("question", "yes", "Yes!")
>>> no = ds.Radio("question", "no", "Maybe later..")
>>> ds.Radios("question", yes, no)
# Renders the same radios but by defining individual components, we can use
# all of the underlying configurations

Parameters:

*args – Arguments for Field.
radios (List[Radio], optional) – List of Radio components.
choices (dict, optional) – Shorthand for simple radios.
small (bool, optional) – Renders small Radios. Defaults to False.
inline (bool, optional) – Renders inline Radios. Defaults to False.
**kwargs – Additional keyword arguments.

property clean¶: Get “clean” data from a field when a form is being processed by a form Backend.

make_radios()¶: Make radios from choices.

insert_divider()¶: Insert “or” if there are more than 2 radios.

class fast_gov_uk.design_system.inputs.FileUpload(*args, **kwargs)¶

Bases: Field

GOV.UK File upload component. Renders a file upload field to help users select and upload a file.

To upload a file, the user can either: use the “Choose file” button or drag and drop a file into the file upload input area.

It is recommended that you should only ask users to upload something if it’s critical to the delivery of your service.

Examples

>>> ds.FileUpload("test")
# Renders a file upload field called "test"

Parameters:

*args – Arguments for Field.
**kwargs – Additional keyword arguments.

property valid_file¶: Is the uploaded file valid?

property clean¶: Get “clean” data from a field when a form is being processed by a form Backend.

class fast_gov_uk.design_system.inputs.DateInput(*args, **kwargs)¶

Bases: Field

GOV.UK Date input component. Renders GDS-style composite field with day, month, year.

You should use the date input component to help users enter a memorable date or one they can easily look up.

Examples

>>> ds.DateInput("dob")
# Renders the classic GOV.UK 3-input - Day, Month, Year - date field.

See fast_gov_uk.design_system.contrib.PastDateInput and fast_gov_uk.design_system.contrib.FutureDateInput for fields that validate whether the date should be in the past or future respectively.

Parameters:

*args – Arguments for Field.
**kwargs – Additional keyword arguments.

property clean¶: Get “clean” data from a field when a form is being processed by a form Backend.

property day_field¶: Day field component.

property month_field¶: Month field component.

property year_field¶: Year field component.

class fast_gov_uk.design_system.inputs.ButtonStyle(*values)¶

Bases: Enum

Enum to define GOV.UK supported button styles to be passed into Button as style param.

fast_gov_uk.design_system.inputs.Button(text: str, style: ButtonStyle = ButtonStyle.PRIMARY, disabled: bool = False, prevent_double_click: bool = False, **kwargs) → FT¶

GOV.UK Button component used to help users carry out an action like starting an application or saving their information.

Write button text in sentence case, describing the action it performs. For example:

“Start now” at the start of your service
“Sign in” to an account a user has already created
“Continue” when the service does not save a user”s information
“Save and continue” when the service does save a user”s information
“Save and come back later” when a user can save their information and come back later
“Add another” to add another item to a list or group
“Pay” to make a payment
“Confirm and send” on a Check answers page that does not have any legal content a user must agree to
“Accept and send” on a Check answers page that has legal content a user must agree to
“Sign out” when a user is signed in to an account

Examples

>>> ds.Button("Submit")
# Renders a default button called "Submit"
>>> ds.Button("Cancel", ButtonStyle.WARNING)
# Renders a warning button
>>> ds.Button("Cancel", disabled=True)
# Renders a disabled button
>>> ds.Button("Cancel", prevent_double_click=True)
# Renders a button with some js that prevents double clicks - useful for payments

Parameters:

text (str) – The text on the Button component.
style (ButtonStyle, optional) – The style of the Button component. Defaults to ButtonStyle.PRIMARY.
disabled (bool, optional) – Disable the button. Defaults to False.
prevent_double_click (bool, optional) – Prevent accidental double clicks. Defaults to False.
**kwargs – Any extra args to pass to fh.Button.

Returns:

A FastHTML Button component.

Return type:

FT

fast_gov_uk.design_system.inputs.StartButton(text: str, href: str, **kwargs) → FT¶

GOV.UK Start Button component for call-to-actions. Does not submit form data.

Examples

>>> ds.StartButton("Lets go")
# Renders a start button with the label "Lets go"
# This button acts more like a link - it results in a GET request instead of POST

Parameters:

text (str) – Text on the Button component.
href (str) – URL of the target page.
**kwargs – Additional keyword arguments.

Returns:

A FastHTML StartButton component.

Return type:

FT

fast_gov_uk.design_system.inputs.ButtonGroup(*buttons: FT, **kwargs) → FT¶

GOV.UK Button Group component.

Use a button group when two or more buttons are placed together.

Examples

>>> continue = ds.Button("Continue")
>>> cancel = ds.Button("Cancel")
>>> ds.ButtonGroup(contiue, cancel)
# Renders a button group

Parameters:

*buttons (FT) – List of Button components.
**kwargs – Additional keyword arguments.

Returns:

A FastHTML component.

Return type:

FT

fast_gov_uk.design_system.inputs.CookieBanner(service_name: str, *content: FT, cookie_page_link: str = '/cookies', cookie_form_link: str = '/cookie-banner', confirmation: bool = False, **kwargs) → FT¶

GOV.UK Cookie Banner component.

Allow users to accept or reject cookies which are not essential to making your service work.

This component needs links to 2 endpoints on the service -

cookie_page_link is a link to the cookies page for your service.

cookie_form_link is a link to the cookies form that processes the data when a user submits their cookie preferences through this component.

Fast-gov-uk comes out of the box with default, minimal implementations of both. In fact, fast-gov-uk comes out of the box with a cookie banner for essentail cookies.

In view of the above, you would only use this component if you are creating a custom cookie banner for your service.

Examples

>>> ds.CookieBanner("Test")
# Renders a standard cookie banner for essential cookies that works out of the box

Parameters:

service_name (str) – Name of the service.
*content (FT) – Content of the CookieConfirmation component.
cookie_page_link (str, optional) – Link to the cookie settings page. Defaults to “/cookies”.
cookie_form_link (str, optional) – Link to the cookie form submission page. Defaults to “/”.
confirmation (bool, optional) – If True, the cookie confirmation is shown. Defaults to False.
**kwargs – Additional keyword arguments.

Returns:

A FastHTML CookieConfirmation component.

Return type:

FT

class fast_gov_uk.design_system.inputs.Fieldset(*fields: Field, name: str = '', legend: str = '', heading: str = 'l', **kwargs)¶

Bases: AbstractField

GOV.UK Fieldset component used to group related form fields.

Use the fieldset component when you need to show a relationship between multiple form inputs. For example, you may need to group a set of text inputs into a single fieldset when asking for an address in your service.

Examples

>>> address1 = ds.TextInput("address1", label="Address line 1")
>>> address2 = ds.TextInput("address2", label="Address line 2")
>>> town = ds.TextInput("town", label="Town or city")
>>> postcode = ds.TextInput("postcode", label="Postcode")
>>> ds.Fieldset(address1, address2, town, postcode)
# Renders an address fieldset containing multiple, related fields

Parameters:

*fields (Field) – Fields to include in the fieldset.
name (str, optional) – Name of the fieldset. Defaults to “”.
legend (str, optional) – The legend text for the fieldset.
heading (str, optional) – Heading size. Defaults to “l”.
**kwargs – Additional keyword arguments.

Inputs¶

fast-gov-uk

Navigation

Related Topics