Components

For a quick reference of all the components and how to add them to a page, see the Component kitchen sink.

Accordion

Why: An accordion is a list of headers that hide or reveal additional content when selected.

How:

1. Define collections of content in the _config.yml file.

collections:
  - borrowing
  - charters

2. Create a folders for each collection in the collections folder. NOTE: Each folder must have an underscore (_) in front of it. For example, if you define a collection called "features," you have to create a folder called _features inside the collections folder.
3. In each collection folder, create Markdown content files for each item. Each file should have a title setting in the front matter, along with the content.

---
title: Name of the feature
---

Content for this feature

4. Add the accordion component to a content file using this line: {% include components/accordion.html collection=site.charters %}.

• The collection setting is entered as site.name-of-your-collection with no quotes.

Where: See FAQ template.

Alert

Why: An alert keeps users informed of important and sometimes time-sensitive changes.

How:

• To add to a content file, enter this line: {% include components/alert.html heading="Warning" text="This form may cause unusual levels of excitement." type="warning" %}.
• Available types are: info, warning, error, success

Where: See Simple form template.

Basic 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.

Breadcrumb

Why: Breadcrumbs provide secondary navigation to help users understand where they are in a website.

How:

• To add to a content file, enter this line: {% include components/breadcrumb.html %}.
• Home and Current Page are included by default.
• The title will be the h1 from the content area (preceded by single # and a space in Markdown) unless you specify a different title in the front matter, like this: title: Something Else. (See the front matter example below.)
• To remove the current page, add this setting to the include statement: current-page=false.
• To add links in between Home and Current Page, add links to the front matter of the content page, like this:

---
layout: grid-container
title: Alternate Page Title
breadcrumbs:
- name: Framework
  url: framework/
- name: Molecules
  url: framework/molecules/
---

Where: See Cards template.

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

Card

Why: Cards contain content and actions about a single subject.

How:

• To add to a content file, enter this line: {% include components/card.html width="tablet:grid-col-4" %}.
• Set the width of the cards using the Grid system, including different settings for different breakpoints as needed.
  • In the example above (tablet:grid-col-4), the card will take up the full width at smaller screens (all 12 columns). Then at the tablet breakpoint, each card will take up 4 columns on a row.
• Each instance of the component can reference its own content/data source that contains multiple cards. To create a new data file:
  1. Create a YAML file similar to the example cards.yml files in the _data folder.
  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/card.html width="col-6" values=site.data.mycards %}.

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 the vertical line character | (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 the vertical line character | (no spaces).
• 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.

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.

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

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.

Side navigation

Why: Hierarchical, vertical navigation to place at the side of a page.

How:

1. Set up a data file with link text and URLs as needed. See _data/sidenav.yml as an example.
2. Set up a content include include with this line: {% include components/side-navigation.html values=site.data.sidenav %}. See _includes/content/side-nav.md as an example.

• Values should reference the name of your data file (without the suffix).

3. On your content page, use the sidebar layout layout: sidebar, and assign the include to the content setting: sidebar: side-nav.md.

• For highlighting current nav, use sidnav-parent and sidenav-child to reference the link text, like this:

sidenav-parent: Southern
sidenav-child: Virginia

Where: See Side navigation 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 the vertical line character | (no spaces).

Where: See Article template.

Text Area

Why: A text area allows users to enter multi-line form content.

How:

• To add to a content file, enter this line: {% include components/text-area.html label="The Label" %}.

Where: See Address 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 components/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 components/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".