Components

Button

Why: A button draws attention to important actions with a large selectable surface.

How:

• To add to a content file, enter this line: {% include components/button.html label="Create" link="index.html" %}.
• Note that the button component uses the a (link) element, not the button element, because for most prototyping purposes it's more useful to simply enter a link of a page you want to go to when pressing the button.
• Other settings:
  • id
  • new-tab (true or false)
  • style

Checkbox

Why: Checkboxes allow users to select one or more options from a list.

How:

• To add to a content file, enter this line: {% include components/checkbox.html labels="Check yourself" %}.
• You can add multiple checkboxes within a single component by including multiple labels, separated by commas (with no spaces), like this: {% include components/checkbox.html labels="This applies,Also this one,Don’t forget about me" %}.
• You can optionally use the “tile” styling by adding tile=true. (No quotes.)
• Note that there are no custom styling options for this component because of the complexity involved.

Where: See Simple form template.

Combo box

Why: A combo box helps users select an item from a large list of options.

How:

1. Create a CSV file with the column heading name.
2. Upload it to the _data folder.
3. In the values setting, reference the data file like this: site.data.FILENAME. Note there are no quotes when referencing this file because it's a separate thing, not text: {% include components/combo-box.html label="State" values=site.data.states %}.

Where: See Address template.

Dropdown

Why: A dropdown allow users to select one of more than a few or less than a dozen or so options.

How:

• To add to a content file, enter this line: {% include components/dropdown.html label="Country" values="Canada,Cuba,Iceland,Ireland,Mexico,United Kingdom,United States" %}.
• Note the values are included directly in the include statement and separated by commas.
• If you have a large number of options, use Combo box instead.
• If you only have a few options, consider using Radio buttons instead.

Where: See Address template.

Header

Why: A header helps users identify where they are and provide a quick, organized way to reach the main sections of a website.

How:

• In the settings (front matter) of a content (markdown) page, add header: true.
• To remove it, change the setting to header: false or remove it.

Where: See Article template.

Link

Why: A link connects users to a different page or further information.

How:

• To add to a content file, enter this line: {% include components/link.html label="Link text" link="index.html" %}.
• Set new-tab to true if you want the link to open in a new window.
• Other settings:
  • id
  • new-tab (true or false)
  • style

Icon

Why: Icons help communicate meaning, actions, status, or feedback.

How:

• Use the filter on the Icon component page to find the name of the icon you want to use.
• Add it to the page, like this: {% include components/icon.html icon="info" %}.
• You can change the size by adding a setting between 3 and 9 to multiply the size by that amount, like this: size="4".
• You can use style settings. For example, to change the color, add this setting: style="text-base".
• Note that icons are added to the page as inline elements, but if they are at the beginning of a paragraph, the paragraph will start on a new line. You can use the float utility to move it next to paragraph text instead of above or below it, like this: style="float-left".

Where: See Create account template.

Prose

Why: Format a block of running text.

How:

• In the settings (front matter) of a content (markdown) page, add prose: true.
• To remove it, change the setting to prose: false or remove it.

Where: See Article template.

Radio buttons

Why: Radio buttons allow users to select exactly one choice from a group.

How:

• To add to a content file, enter this line: {% include components/radio-buttons.html legend="I am legend" labels="Yes,No,Maybe so" %}.
• You can optionally use the “tile” styling by adding tile=true. (No quotes.)
• Note that there are no custom styling options for this component because of the complexity involved.

Where: See Simple form template.

Tag

Why: A tag draws attention to new or categorized content elements.

How:

• To add to a content file, enter this line: {% include components/tag.html labels="one,two,three" %}.
• As shown above, you can add multiple tags using one component instance with multiple labels separated by commas. (No spaces.)

Where: See Article template.

Text input

Why: A text input allows users to enter any combination of letters, numbers, or symbols.

How:

• To add to a content file, enter this line: {% include text-input.html label="The Label" type="text" %}.
• The label is the text that appears above the input.
• The id is automatically generated in a url-friendly format from the label. For example, The Label is converted to the-label.
• The default type is text, but there are other options that affect the behavior of the input:
  • Password
  • Email
  • Phone
  • Date
  • Number
• Other settings:
  • style

Where: See Create account template.

Tooltip

Why: A tooltip provides additional context when hovering over or focusing on an interactive element.

How:

• To add a tooltip to a button or link component, add the usa-tooltip style and text using the tooltip setting, like this: {% include button.html label="Create" link="#" style="usa-tooltip" tooltip="Click me to create an account" %}
• Change the position by adding the tooltip-position setting, like this: tooltip-position="right".