Input
An input is where I provide a short answer to a question in an online form.
The Input component is the most common form component for receiving user information on an online form. There are several types of inputs (text being one of them) that suggest the type of information they can receive. Input types are enhanced with icon prefixes, postfixes, or masks to help users enter the correct information. They are always paired with a label inside a Form group component.
Details
- Extends: USWDS Text input component
- Customization: Styles
- Modifier:
.cfa-input,.cfa-input-group
The Input extends the USWDS Text input component. Further customization is applied using the CSS modifier(s) .cfa-input, .cfa-input-group to add styles defined in a custom stylesheet.
Modifier. A modifier is a class name that applies a variant, type, or extended style customization to modify the component's visual appearance.
Examples
The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.
<div>
<input class="usa-input cfa-input" type="text" id="input-66b475abd71ef" name="input['66b475abd71ef']">
</div>
Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.
{
"input": {
"modifier": "cfa-input",
"id": "input-66b475abd71ef",
"name": "input['66b475abd71ef']",
"type": "text"
}
}
The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.
<div>
<input class="usa-input cfa-input" type="email" id="input-d819389b006f8" name="input['d819389b006f8']">
</div>
Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.
{
"input": {
"modifier": "cfa-input",
"id": "input-d819389b006f8",
"name": "input['d819389b006f8']",
"type": "email"
}
}
The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.
<div class="usa-input-group cfa-input-group">
<div class="usa-input-prefix" aria-hidden="true">$</div>
<input class="usa-input cfa-input text-end" type="text" id="input-387eb3d91a49f" name="input['387eb3d91a49f']" placeholder="0.00" inputmode="decimal" data-js="mask-dollars">
</div>
Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.
{
"inputGroup": {
"modifier": "usa-input-group cfa-input-group"
},
"input": {
"modifier": "cfa-input text-end",
"id": "input-387eb3d91a49f",
"name": "input['387eb3d91a49f']",
"type": "text",
"prefixText": "$",
"placeholder": "0.00",
"inputmode": "decimal",
"js": "mask-dollars"
}
}
The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.
<div class="usa-input-group cfa-input-group">
<input class="usa-input cfa-input text-end" type="text" id="input-3fdb01ebdd2b2" name="input['3fdb01ebdd2b2']" inputmode="decimal">
<div class="usa-input-suffix" aria-hidden="true">%</div>
</div>
Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.
{
"inputGroup": {
"modifier": "usa-input-group cfa-input-group"
},
"input": {
"modifier": "cfa-input text-end",
"id": "input-3fdb01ebdd2b2",
"name": "input['3fdb01ebdd2b2']",
"type": "text",
"postfixText": "%",
"inputmode": "decimal"
}
}
The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.
<div class="usa-input-group cfa-input-group">
<div class="usa-input-prefix" aria-hidden="true">+1</div>
<input class="usa-input cfa-input" type="tel" id="input-8a4e82f90f85b" name="input['8a4e82f90f85b']" pattern="([0-9]{3}) [0-9]{3}-[0-9]{4}" inputmode="tel" data-js="mask-tel">
</div>
Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.
{
"inputGroup": {
"modifier": "usa-input-group cfa-input-group"
},
"input": {
"modifier": "cfa-input",
"id": "input-8a4e82f90f85b",
"name": "input['8a4e82f90f85b']",
"type": "tel",
"pattern": "([0-9]{3}) [0-9]{3}-[0-9]{4}",
"prefixText": "+1",
"inputmode": "tel",
"js": "mask-tel"
}
}
The HTML for the demonstration above is rendered using context passed to the component's Thymeleaf template fragment. Learn how to include component templates for Thymeleaf and Ruby in the source and usage section.
<div>
<input class="usa-input cfa-input" type="text" id="input-f17c1b72bbb55" name="input['f17c1b72bbb55']" pattern="[0-9]{3}-[0-9]{2}-[0-9]{4}" inputmode="numeric" data-js="mask-ssn">
</div>
Context is the information necessary to configure and render a component template to HTML. It may include plain text strings, HTML, class names, IDs or other HTML attribute values. The context here is defined as JSON but the root attributes are translated to different variable syntaxes for Thymeleaf and Ruby templates. Learn how to pass these variables to each component template in the source and usage section.
{
"input": {
"modifier": "cfa-input",
"id": "input-f17c1b72bbb55",
"name": "input['f17c1b72bbb55']",
"type": "text",
"pattern": "[0-9]{3}-[0-9]{2}-[0-9]{4}",
"inputmode": "numeric",
"js": "mask-ssn"
}
}
Guidance
Inputs vs. Textareas. When longer form content needs to be entered the textarea component is used.
Form groups. Form questions with input components always use the form group component to wrap the input with a visible label element.
Refer to additional guidance on the USWDS documentation site.
USWDS documentation siteAdditional references
Accessibility
Refer to additional accessibility guidance on the USWDS documentation site.
Checklist Key
Design library component
Source and usage
- Sass stylesheet:
./_cfa-input.scss - Thymeleaf template fragment:
./cfa-input.th.html - Embedded Ruby (ERB) partial template:
./_cfa-input.html.erb - JavaScript
is used to provide a formatting (mask) utility for U.S. Dollars, U.S. Phone, and Social Security Number input types.
Guidance on individual module loading will added. Currently, there is one script that imports all modules. The source is located at
@codeforamerica/js/index.js. This entrypoint is compiled using Rollup.js and distributed to@codeforamerica/dist/js/default.js.
Below is a demonstration of customizing the component theme settings. Refer to the theme and package-level settings documentation.
// Theme-level settings
@use 'cfa-uswds-theme' with (
// Global theme settings that affect the component, changing these will affect other components
$cfa-color-base-lightest: 'gray-warm-4', // Affects the background color of the input
$cfa-color-base-lighter: 'gray-warm-10', // Affects the color of the input inset border
$cfa-color-base-ink: 'gray-warm-90' // Affects the text and border color of the input
);
// Package-level settings
@use 'cfa-core' with (
$cfa-form-elements-border-width: 2px,
$cfa-form-elements-padding-y: 2,
$cfa-form-elements-padding-x: 2.5,
$cfa-input-height: 8
);
Refer to the usage documentation for additional USWDS theme settings.
@use "uswds-core" with ( /* additional USWDS theme settings */ );
This is the pre-rendered template fragment from the package. It is the same template used to render the demonstrations above. You may copy and paste from this example or use the template using the th:block th:replace tag. See the example below.
<div th:fragment="input(input, inputGroup)" th:if="${input}" th:class="${inputGroup.modifier}">
<div th:if="${input.prefix}" class="usa-input-prefix" aria-hidden="true">
<svg aria-hidden="true" role="img" focusable="false" class="usa-icon">
<use href="${input.prefix}"></use>
</svg>
</div>
<div th:if="${input.prefixText}" class="usa-input-prefix" aria-hidden="true" th:text="${input.prefixText}">$</div>
<input class="usa-input" th:classappend="${input.modifier}" th:attr="type=${input.type},id=${input.id},name=${input.name},aria-invalid=${input.ariaInvalid},aria-describedby=${input.ariaDescribedby},required=${input.required},pattern=${input.pattern},placeholder=${input.placeholder},value=${input.value},inputmode=${input.inputmode},maxlength=${input.maxlength},autocapitalize=${input.autocapitalize},autocorrect=${input.autocorrect},autocomplete=${input.autocomplete},accept=${input.accept},multiple=${input.multiple},data-js=${input.js}">
<div th:if="${input.postfix}" class="usa-input-suffix" aria-hidden="true">
<svg aria-hidden="true" role="img" focusable="false" class="usa-icon">
<use href="${input.prefix}"></use>
</svg>
</div>
<div th:if="${input.postfixText}" class="usa-input-suffix" aria-hidden="true" th:text="${input.postfixText}">.00</div>
</div>
Below is an example of how to use the fragment from the package directory using the th:block th:replace inclusion tag. Replace the fragment parameters using your variables or context.
<th:block th:replace="~{packages/cfa-input/cfa-input.th :: input(${input}, ${inputGroup})}" />
This is the pre-rendered partial template from the package. You may copy and paste from this example or use the template directly from the path.
<div <% if defined?(inputGroup) && inputGroup['modifier'] %>class="<%= inputGroup['modifier'] %>"<% end %>>
<% if input['prefix'] %><div class="usa-input-prefix" aria-hidden="true">
<svg aria-hidden="true" role="img" focusable="false" class="usa-icon">
<use href="<%= input['prefix'] %>"></use>
</svg>
</div><% end %>
<% if input['prefixText'] %><div class="usa-input-prefix" aria-hidden="true"><%= input['prefixText'] %></div><% end %>
<input class="usa-input<% if input['modifier'] %> <%= input['modifier'] %><% end %>"
<% if input['type'] %> type="<%= input['type'] %>"<% end %>
<% if input['id'] %> id="<%= input['id'] %>"<% end %>
<% if input['name'] %> name="<%= input['name'] %>"<% end %>
<% if input['aria-invalid'] %> aria-invalid="<%= input['ariaInvalid'] %>"<% end %>
<% if input['aria-describedby'] %> aria-describedby="<%= input['ariaDescribedby'] %>"<% end %>
<% if input['required'] %> required<% end %>
<% if input['pattern'] %> pattern="<%= input['pattern'] %>"<% end %>
<% if input['placeholder'] %> placeholder="<%= input['placeholder'] %>"<% end %>
<% if input['value'] %> value="<%= input['value'] %>"<% end %>
<% if input['inputmode'] %> inputmode="<%= input['inputmode'] %>"<% end %>
<% if input['maxlength'] %> maxlength="<%= input['maxlength'] %>"<% end %>
<% if input['autocapitalize'] %> autocapitalize="<%= input['autocapitalize'] %>"<% end %>
<% if input['autocorrect'] %> autocorrect="<%= input['autocorrect'] %>"<% end %>
<% if input['autocomplete'] %> autocomplete="<%= input['autocomplete'] %>"<% end %>
<% if input['js'] %> data-js="<%= input['js'] %>"<% end %>>
<% if input['posfix'] %><div class="usa-input-suffix" aria-hidden="true">
<svg aria-hidden="true" role="img" focusable="false" class="usa-icon">
<use href="<%= input['posfix'] %>"></use>
</svg>
</div><% end %>
<% if input['postfixText'] %><div class="usa-input-suffix" aria-hidden="true"><%= input['postfixText'] %></div><% end %>
</div>
Below is an example of how to include the partial in a view from the package directory using the Ruby ERB class. Replace the argument values using your variables or context. In a Rails environment, the render method can be used instead with the same hash values.
<%= ERB.new(File.read('packages/cfa-input/_cfa-input.html.erb'), 0, 0, '@input').result_with_hash({input: input}) %>