Skip to main content

Toolbar

A toolbar has all of the important links and features I need from a website. It might also have a time-sensitive alert.

The Toolbar component is used as the header landmark for a page and appears globally on all site pages. It contains the primary navigation and buttons for the main features of the site that may include the homepage link, chat, language selector, or authentication links. It may also contain a site alert to provide the user with important or time sensitive information.

Details

The Toolbar is a custom component created using USWDS CSS Utilities.

Examples

Toolbar

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.

<header>
  <div class="grid-container display-flex flex-justify flex-align-center tablet:padding-y-2">
    <div>
      <a href="https://codeforamerica.github.io/uswds/">
        <svg xmlns="http://www.w3.org/2000/svg" class="display-block tablet:display-none" role="img" aria-hidden="true" style="width: 101px; height: 82px">
          <use href="#logo-cfa-stacked">
          </use>
        </svg>
        <svg xmlns="http://www.w3.org/2000/svg" class="display-none tablet:display-block" role="img" aria-hidden="true" style="width: 161px; height: 49px">
          <use href="#logo-cfa-long">
          </use>
        </svg>
        <span class="usa-sr-only">Code for America</span>
      </a>
    </div>
    <div class="display-flex">
      <button class="usa-button cfa-button usa-button--primary flex-1">
        <svg class="usa-icon display-none mobile-lg:display-inline-block" aria-hidden="true" focusable="false" role="img">
          <use href="https://codeforamerica.github.io/uswds/assets/img/sprite.svg#chat"></use>
        </svg>
        <span>Chat</span>
      </button>
      <div class="display-flex flex-align-center">
        <button class="usa-button cfa-button usa-button--outline cfa-button--sub-label flex-auto margin-0 desktop:display-none">
          <svg class="usa-icon display-none mobile-lg:display-inline-block" aria-hidden="true" focusable="false" role="img">
            <use href="https://codeforamerica.github.io/uswds/assets/img/sprite.svg#translate"></use>
          </svg>
          <span> Translate <span class="usa-sr-only"> to </span>
            <small class="cfa-button__sub-label">
              <span lang="en">English</span>, <span lang="es">Español</span>
            </small>
          </span>
        </button>
        <nav aria-label="Translate" class="display-none desktop:display-inline-block">
          <a lang="en" href="?lang=en" class="margin-left-1">English</a>
          <a lang="es" href="?lang=es" class="margin-left-1">Español</a>
        </nav>
      </div>
    </div>
  </div>
</header>

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.

{
  "alert": {
    "modifier": "cfa-alert cfa-site-alert usa-alert--info margin-0 border-top-0 border-x-0",
    "role": "status",
    "text": "This site is for demonstration purposes only."
  },
  "container": {
    "modifier": "tablet:padding-y-2"
  },
  "home": {
    "href": "https://codeforamerica.github.io/uswds/"
  },
  "logo": {
    "alt": {
      "modifier": "usa-sr-only",
      "text": "Code for America"
    },
    "default": {
      "href": "#logo-cfa-stacked",
      "style": "width: 101px; height: 82px"
    },
    "tablet": {
      "href": "#logo-cfa-long",
      "style": "width: 161px; height: 49px"
    }
  },
  "chat": "https://codeforamerica.github.io/uswds/assets/img/sprite.svg#chat",
  "languageSelector": "https://codeforamerica.github.io/uswds/assets/img/sprite.svg#translate"
}

Accessibility

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

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

Checklist Key

  • Passes
    Passes
  • Unchecked
    Unchecked

Design library component

Source and usage

Package: @codeforamerica/uswds/packages/cfa-toolbar

  • Thymeleaf template fragment: ./cfa-toolbar.th.html
  • Embedded Ruby (ERB) partial template: ./_cfa-toolbar.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.
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.

<!-- In production environments a site wide alert would be embedded here -->
<!-- In production environments the skip nav link would be embedded here -->
<header th:fragment="toolbar(modifier, alert, container, startEl, startElModifier, home, logo, endEl, endElModifier, chat, languageSelector, links)" th:class="${modifier}">
  <div class="grid-container display-flex flex-justify flex-align-center" th:classappend="${container.modifier}">
    <div th:if="${startEl}" th:replace="${startEl}">
      Toolbar start contents
    </div>
    <div th:unless="${startEl}" th:classappend="${startElModifier}">
      <a th:href="${home.href}" th:class="${home.modifier}">
        <svg th:if="${logo.default}" th:attr="style=${logo.default.style}" xmlns="http://www.w3.org/2000/svg" class="display-block tablet:display-none" role="img" aria-hidden="true">
          <use th:href="${logo.default.href}">
        </svg>
        <svg th:if="${logo.tablet}" th:attr="style=${logo.tablet.style}" xmlns="http://www.w3.org/2000/svg" class="display-none tablet:display-block" role="img" aria-hidden="true">
          <use th:href="${logo.tablet.href}">
        </svg>
        <span th:if="${logo.alt}" th:class="${logo.alt.modifier}" th:text="${logo.alt.text}">Logo text</span>
      </a>
    </div>
    <div th:if="${endEl}" th:replace="${endEl}">
      Toolbar end contents
    </div>
    <div th:unless="${endEl}" class="display-flex" th:classappend="${endElModifier}">
      <button th:if="${chat}" class="usa-button cfa-button usa-button--primary flex-1">
        <svg class="usa-icon display-none mobile-lg:display-inline-block" aria-hidden="true" focusable="false" role="img">
          <use th:href="${chat}"></use>
        </svg>
        <span>Chat</span>
      </button>
      <div th:if="${languageSelector}" class="display-flex flex-align-center">
        <button class="usa-button cfa-button usa-button--outline cfa-button--sub-label flex-auto margin-0 desktop:display-none">
          <svg class="usa-icon display-none mobile-lg:display-inline-block" aria-hidden="true" focusable="false" role="img">
            <use th:href="${languageSelector}"></use>
          </svg>
          <span>
            Translate <span class="usa-sr-only"> to </span>
            <small class="cfa-button__sub-label">
              <span lang="en">English</span>,
              <span lang="es">Español</span>
            </small>
          </span>
        </button>
        <nav aria-label="Translate" class="display-none desktop:display-inline-block">
          <a lang="en" href="?lang=en" class="margin-left-1" th:classappend="${links.modifier}">English</a>
          <a lang="es" href="?lang=es" class="margin-left-1" th:classappend="${links.modifier}">Español</a>
        </nav>
      </div>
    </div>
  </div>
</header>
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-toolbar/cfa-toolbar.th :: toolbar(${modifier}, ${container}, ${startEl}, ${startElModifier}, ${home}, ${logo}, ${endEl}, ${endElModifier}, ${chat}, ${languageSelector}, ${links})}" />
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.

<!-- In production environments a site wide alert would be embedded here -->
<!-- In production environments the skip nav link would be embedded here -->
<header<% if defined?(modifier) %> class="<%= modifier %>"<% end %>>
  <div class="grid-container display-flex flex-justify flex-align-center<% if container['modifier'] %> <%= container['modifier'] %><% end %>">
    <% if defined?(startEl) %>
      <%= startEl %>
    <% else %>
    <div<% if defined?(startElModifier) %> class="<%= startElModifier %>"<% end %>>
      <a href="<%= home['href'] %>"<% if home['modifier'] %> class="<%= home['modifier'] %>"<% end %>>
        <% if logo['default'] %><svg<% if logo['default']['style'] %> style="<%= logo['default']['style'] %>"<% end %> xmlns="http://www.w3.org/2000/svg" class="display-block tablet:display-none" role="img" aria-hidden="true">
          <use href="<%= logo['default']['href'] %>">
        </svg><% end %>
        <% if logo['tablet'] %><svg<% if logo['tablet']['style'] %> style="<%= logo['tablet']['style'] %>"<% end %> xmlns="http://www.w3.org/2000/svg" class="display-none tablet:display-block" role="img" aria-hidden="true">
          <use href="<%= logo['tablet']['href'] %>">
        </svg><% end %>
        <% if logo['alt'] %><span<% if logo['alt'].has_key?('modifier') %> class="<%= logo['alt']['modifier'] %>"<% end %>><%= logo['alt']['text'] %></span><% end %>
      </a>
    </div>
    <% end %>
    <% if defined?(endEl) %>
      <%= endEl %>
    <% else %>
    <div class="display-flex<% if defined?(endElModifier) %> <%= endElModifier %><% end %>">
      <% if defined?(chat) %><button class="usa-button cfa-button usa-button--primary flex-1">
        <svg class="usa-icon display-none mobile-lg:display-inline-block" aria-hidden="true" focusable="false" role="img">
          <use href="<%= chat %>"></use>
        </svg>
        <span>Chat</span>
      </button><% end %>
      <% if defined?(languageSelector) %><div class="display-flex flex-align-center">
        <button class="usa-button cfa-button usa-button--outline cfa-button--sub-label flex-auto margin-0 desktop:display-none">
          <svg class="usa-icon display-none mobile-lg:display-inline-block" aria-hidden="true" focusable="false" role="img">
            <use href="<%= languageSelector %>"></use>
          </svg>
          <span>
            Translate <span class="usa-sr-only"> to </span>
            <small class="cfa-button__sub-label">
              <span lang="en">English</span>,
              <span lang="es">Español</span>
            </small>
          </span>
        </button>
        <nav aria-label="Translate" class="display-none desktop:display-inline-block">
          <a lang="en" href="?lang=en" class="margin-left-1<% if defined?(links) && links['modifier'] %> <%= links['modifier'] %><% end %>">English</a>
          <a lang="es" href="?lang=es" class="margin-left-1<% if defined?(links) && links['modifier'] %> <%= links['modifier'] %><% end %>">Español</a>
        </nav>
      </div><% end %>
    </div>
    <% end %>
  </div>
</header>
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-toolbar/_cfa-toolbar.html.erb'), 0, 0, '@toolbar').result_with_hash({modifier: modifier, startEl: startEl, startElModifier: startElModifier, endEl: endEl, endElModifier: endElModifier, chat: chat, languageSelector: languageSelector, container: container, home: home, logo: logo}) %>

uswds.codeforamerica.org

Learn more about Code for America by visiting codeforamerica.org