Skip to main content

Memorable date

A memorable date is one I can easily recall without having to pick it in a calendar.

The Memorable date component is used to allow the user to enter a date in an online form they are very familiar with, such as their birthday.

Details

  • Extends: USWDS Memorable date component
  • Customization: Styles
  • Modifier: .cfa-memorable-date, .cfa-legend, .cfa-label, .cfa-hint, .cfa-select, .cfa-input

The Memorable date extends the USWDS Memorable date component. Further customization is applied using the CSS modifier(s) .cfa-memorable-date, .cfa-legend, .cfa-label, .cfa-hint, .cfa-select, .cfa-input 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

Memorable date
What is your date of birth? (required)
For example January / 1 / 2000

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.

<fieldset class="usa-fieldset">
  <legend class="usa-legend cfa-legend">
    <span>What is your date of birth? <abbr class="usa-hint usa-hint--required cfa-hint text-normal">(required)</abbr>
    </span>
  </legend>
  <div class="usa-hint cfa-hint" id="hint-8a00c9d27a44">For example January / 1 / 2000</div>
  <div class="usa-memorable-date cfa-memorable-date">
    <div>
      <div class="usa-form-group usa-form-group--month usa-form-group--select" id="form-group-month-8a00c9d27a44">
        <label class="usa-label cfa-label text-normal" for="month-8a00c9d27a44">
          <span>Month</span>
        </label>
        <div>
          <select class="usa-select cfa-select" id="month-8a00c9d27a44" name="month['8a00c9d27a44']" aria-describedby="hint-8a00c9d27a44">
            <option selected="true">Click to select month</option>
            <option disabled="true">---</option>
            <option value="1">01 - January</option>
            <option value="2">02 - February</option>
            <option value="3">03 - March</option>
            <option value="4">04 - April</option>
            <option value="5">05 - May</option>
            <option value="6">06 - June</option>
            <option value="7">07 - July</option>
            <option value="8">08 - August</option>
            <option value="9">09 - September</option>
            <option value="10">10 - October</option>
            <option value="11">11 - November</option>
            <option value="12">12 - December</option>
          </select>
        </div>
      </div>
    </div>
    <div>
      <div class="usa-form-group usa-form-group--day" id="form-group-day-8a00c9d27a44">
        <label class="usa-label cfa-label text-normal" for="day-8a00c9d27a44">
          <span>Day</span>
        </label>
        <div>
          <div>
            <input class="usa-input cfa-input" type="text" id="day-8a00c9d27a44" name="day['8a00c9d27a44']" aria-describedby="hint-8a00c9d27a44" pattern="[0-9]*" inputmode="numeric" maxlength="2">
          </div>
        </div>
      </div>
    </div>
    <div>
      <div class="usa-form-group usa-form-group--year" id="form-group-year-8a00c9d27a44">
        <label class="usa-label cfa-label text-normal" for="year-8a00c9d27a44">
          <span>Year</span>
        </label>
        <div>
          <div>
            <input class="usa-input cfa-input" type="text" id="year-8a00c9d27a44" name="year['8a00c9d27a44']" aria-describedby="hint-8a00c9d27a44" pattern="[0-9]*" inputmode="numeric" maxlength="4">
          </div>
        </div>
      </div>
    </div>
  </div>
</fieldset>

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.

{
  "modifier": "cfa-memorable-date",
  "fieldset": {
    "hint": {
      "text": "For example January / 1 / 2000",
      "id": "hint-8a00c9d27a44",
      "modifier": "cfa-hint"
    },
    "legend": {
      "text": "What is your date of birth? <abbr class=\"usa-hint usa-hint--required cfa-hint text-normal\">(required)</abbr>",
      "modifier": "cfa-legend",
      "modifierHint": "cfa-hint"
    }
  },
  "month": {
    "type": "select",
    "modifier": "usa-form-group--month usa-form-group--select",
    "id": "form-group-month-8a00c9d27a44",
    "label": {
      "text": "Month",
      "for": "month-8a00c9d27a44",
      "modifier": "cfa-label text-normal",
      "modifierHint": "cfa-hint"
    },
    "selectEl": {
      "modifier": "cfa-select",
      "id": "month-8a00c9d27a44",
      "name": "month['8a00c9d27a44']",
      "ariaDescribedby": "hint-8a00c9d27a44",
      "default": {
        "label": "Click to select month",
        "selected": "true"
      },
      "options": [
        {
          "label": "---",
          "disabled": "true"
        },
        {
          "value": "1",
          "label": "01 - January"
        },
        {
          "value": "2",
          "label": "02 - February"
        },
        {
          "value": "3",
          "label": "03 - March"
        },
        {
          "value": "4",
          "label": "04 - April"
        },
        {
          "value": "5",
          "label": "05 - May"
        },
        {
          "value": "6",
          "label": "06 - June"
        },
        {
          "value": "7",
          "label": "07 - July"
        },
        {
          "value": "8",
          "label": "08 - August"
        },
        {
          "value": "9",
          "label": "09 - September"
        },
        {
          "value": "10",
          "label": "10 - October"
        },
        {
          "value": "11",
          "label": "11 - November"
        },
        {
          "value": "12",
          "label": "12 - December"
        }
      ]
    }
  },
  "day": {
    "modifier": "usa-form-group--day",
    "id": "form-group-day-8a00c9d27a44",
    "label": {
      "text": "Day",
      "for": "day-8a00c9d27a44",
      "modifier": "cfa-label text-normal",
      "modifierHint": "cfa-hint"
    },
    "input": {
      "modifier": "cfa-input",
      "id": "day-8a00c9d27a44",
      "name": "day['8a00c9d27a44']",
      "type": "text",
      "inputmode": "numeric",
      "maxlength": "2",
      "pattern": "[0-9]*",
      "ariaDescribedby": "hint-8a00c9d27a44"
    }
  },
  "year": {
    "modifier": "usa-form-group--year",
    "id": "form-group-year-8a00c9d27a44",
    "label": {
      "text": "Year",
      "for": "year-8a00c9d27a44",
      "modifier": "cfa-label text-normal",
      "modifierHint": "cfa-hint"
    },
    "input": {
      "modifier": "cfa-input",
      "id": "year-8a00c9d27a44",
      "name": "year['8a00c9d27a44']",
      "type": "text",
      "inputmode": "numeric",
      "minlength": "4",
      "maxlength": "4",
      "pattern": "[0-9]*",
      "ariaDescribedby": "hint-8a00c9d27a44"
    }
  }
}

Guidance

Age. If you are looking to evaluate age consider asking for their age using a Form group with text input component instead of date of birth using the memorable date component.

Month. A text input component as opposed to a select component for the month is supported.

Fieldsets vs. form groups. Form questions with multiple inputs including checkbox, button, and memorable date components always use the fieldset component to group available options and a nested legend element. Other form element components with singular text inputs, text areas, and selects, will use the form group component.

Fieldset. Refer to fieldset documentation.

Form group. Refer to form group documentation.

Select. Refer to select documentation.

Text input. Refer to text input documentation.

Refer to additional guidance on the USWDS documentation site.

USWDS documentation site

Additional references

  1. Date of birth | U.S. Web Design System (USWDS)
  2. Date input | GOV.UK Design System
  3. Memorable date | VA.gov Design System

Accessibility

  • Unchecked
    Customization to the visual appearance of the Memorable date has been verified for WCAG 2.1 AA contrast minimum success.
  • Unchecked
    The Memorable date examples pass manual audits (WCAG 2.1 AA using axe or Lighthouse).
  • Unchecked
    The Memorable date achieves WCAG 2.1 AA resizing success.
    Resizing text up to 200% without loss of content or functionality.
  • Unchecked
    The Memorable date passes keyboard interaction tests.
    No keyboard test has been created.
  • Unchecked
    The Memorable date passes screen reader interaction tests.

  • Unchecked
    Guidance on ensuring Memorable date accessibility has been provided in this documentation.

Refer to additional accessibility guidance on the USWDS documentation site.

Checklist Key

  • Passes
    Passes
  • Unchecked
    Unchecked

Design library component

Source and usage

Package: @codeforamerica/uswds/packages/cfa-memorable-date

  • Sass stylesheet: ./_cfa-memorable-date.scss
  • Thymeleaf template fragment: ./cfa-memorable-date.th.html
  • Embedded Ruby (ERB) partial template: ./_cfa-memorable-date.html.erb
Packages are collections of functionality that make up a component. Typically, they include stylesheets, templates, and scripts. Learn more about packages on the USWDS documentation site.
Sass theme settings

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 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,
  $cfa-select-height: 8
);
USWDS theme settings

Refer to the usage documentation for additional USWDS theme settings.

@use "uswds-core" with ( /* additional USWDS theme settings */ );
Thymeleaf template fragment

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.

<fieldset th:fragment="memorableDate(fieldset, id, modifier, month, day, year)" class="usa-fieldset" th:classappend="${fieldset.modifier}" th:attr="id=${id}">
  <legend class="usa-legend" th:classappend="${fieldset.legend.modifier}" th:attr="id=${fieldset.legend.id},tabindex=${fieldset.legend.tabindex}">
    <span th:utext="${fieldset.legend.text}">Legend</span>
  </legend>
  <div th:if="${fieldset.hint}" class="usa-hint" th:classappend="${fieldset.hint.modifier}" th:attr="id=${fieldset.hint.id}" th:utext="${fieldset.hint.text}">Hint</div>
  <div th:if="${fieldset.error}">
    <span th:each="error: ${fieldset.error}" class="usa-error-message" th:attr="id=${error.id},role=${error.role},aria-live=${error.ariaLive}" th:utext="${error.text}">Message</span>
  </div>
  <div class="usa-memorable-date" th:classappend="${modifier}">
    <div th:if="${month.selectEl}">
      <th:block th:replace="~{packages/cfa-form-group/cfa-form-group.th :: formGroup(${month.modifier}, ${month.id}, ${month.label}, '', '', ${month.selectEl}, ${month.hint}, ${month.error}, '')}" />
    </div>
    <div th:if="${month.input}">
      <th:block th:replace="~{packages/cfa-form-group/cfa-form-group.th :: formGroup(${month.modifier}, ${month.id}, ${month.label}, ${month.input}, '', '', ${month.hint}, ${month.error}, '')}" />
    </div>
    <div th:if="${day.input}">
      <th:block th:replace="~{packages/cfa-form-group/cfa-form-group.th :: formGroup(${day.modifier}, ${day.id}, ${day.label}, ${day.input}, '', '', ${day.hint}, ${day.error}, '')}" />
    </div>
    <div th:if="${year.input}">
      <th:block th:replace="~{packages/cfa-form-group/cfa-form-group.th :: formGroup(${year.modifier}, ${year.id}, ${year.label}, ${year.input}, '', '', ${year.hint}, ${year.error}, '')}" />
    </div>
  </div>
</fieldset>
Template fragment inclusion

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-memorable-date/cfa-memorable-date.th :: memorableDate(${fieldset}, ${id}, ${modifier}, ${month}, ${day}, ${year})}" />
ERB template partial

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.

<fieldset class="usa-fieldset<% if fieldset['modifier'] %> <%= fieldset['modifier'] %><% end %>"<% if defined?(id) %> id="<%= id %>"<% end %>>
  <legend class="usa-legend<% if fieldset['legend']['modifier'] %> <%= fieldset['legend']['modifier'] %><% end %>"<% if fieldset['legend']['id'] %> id="<%= fieldset['legend']['id'] %>"<% end %><% if fieldset['legend']['for'] %> for="<%= fieldset['legend']['for'] %>"<% end %><% if fieldset['legend']['tabindex'] %> tabindex="<%= fieldset['legend']['tabindex'] %>"<% end %>>
    <span><%= fieldset['legend']['text'] %></span>
  </legend>
  <% if fieldset['hint'] %><div class="usa-hint<% if fieldset['hint']['modifier'] %> <%= fieldset['hint']['modifier'] %><% end %>"<% if fieldset['hint']['id'] %> id="<%= fieldset['hint']['id'] %>"<% end %>><%= fieldset['hint']['text'] %></div><% end %>
  <% if fieldset['error'] %><div>
    <% fieldset['error'].each do |error| %>
    <span class="usa-error-message"<% if error['id'] %> id="<%= error['id'] %>"<% end %><% if error['role'] %> role="<%= error['role'] %>"<% end %><% if error['ariaLive'] %> aria-live="<%= error['ariaLive'] %>"<% end %>><%= error['text'] %></span>
    <% end %>
  </div><% end %>
  <div class="usa-memorable-date<% if defined?(modifier) %> <%= modifier %><% end %>">
    <% if month['selectEl'] %><div>
      <%= ERB.new(File.read('packages/cfa-form-group/_cfa-form-group.html.erb'), 0, 0, '@month')
        .result_with_hash({
          modifier: (month['modifier'] if month['modifier']),
          id: (month['id'] if month['id']),
          label: (month['label'] if month['label']),
          hint: (month['hint'] if month['hint']),
          error: (month['error'] if month['error']),
          selectEl: month['selectEl']
        }.compact) %>
    </div><% end %>
    <% if month['input'] %><div>
      <%= ERB.new(File.read('packages/cfa-form-group/_cfa-form-group.html.erb'), 0, 0, '@month')
        .result_with_hash({
          modifier: (month['modifier'] if month['modifier']),
          id: (month['id'] if month['id']),
          label: (month['label'] if month['label']),
          hint: (month['hint'] if month['hint']),
          error: (month['error'] if month['error']),
          input: month['input']
        }.compact) %>
    </div><% end %>
    <% if day['input'] %><div>
      <%= ERB.new(File.read('packages/cfa-form-group/_cfa-form-group.html.erb'), 0, 0, '@day')
        .result_with_hash({
          modifier: (day['modifier'] if day['modifier']),
          id: (day['id'] if day['id']),
          label: (day['label'] if day['label']),
          hint: (day['hint'] if day['hint']),
          error: (day['error'] if day['error']),
          input: day['input']
        }.compact) %>
    </div><% end %>
    <% if year['input'] %><div>
      <%= ERB.new(File.read('packages/cfa-form-group/_cfa-form-group.html.erb'), 0, 0, '@year')
        .result_with_hash({
          modifier: (year['modifier'] if year['modifier']),
          id: (year['id'] if year['id']),
          label: (year['label'] if year['label']),
          hint: (year['hint'] if year['hint']),
          error: (year['error'] if year['error']),
          input: year['input']
        }.compact) %>
    </div><% end %>
  </div>
</fieldset>
Partial render

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-memorable-date/_cfa-memorable-date.html.erb'), 0, 0, '@memorableDate').result_with_hash({id: id, modifier: modifier, fieldset: fieldset, month: month, day: day, year: year}) %>

uswds.codeforamerica.org

Learn more about Code for America by visiting codeforamerica.org