Sidebar widgets are flexible containers that provide a lot of patterns that are helpful in a variety of sidebar uses.
In its simplest form, the sidebar widget is an element with class
.s-sidebarwidget and a child of class
This sets up a sidebar widget with the appropriate inner spacing, and you can put into it whatever you want.
By default the content is a flex container. If you require
display: block instead, add the
Oftentimes, your widget will be a list of similar, relatively simple items. By giving the
s-sidebarwidget--content a modifier class
s-sidebarwidget__items, and giving the items a class of
s-sidebarwidget--item, the content will be spaced out nicely.
In this case, each item is a flex container by default. If you require
display: block instead, specifically add the
d-block class to the
s-sidebarwidget--item, or add the
s-sidebarwidget__block-items modifier class to the
s-sidebarwidget--content to make the change to all items.
There is built-in support for
table content. The
table element should have the classes
s-sidebarwidget--content s-sidebarwidget__items, and the
tr elements should be
If your items are more complex than that, whitespace may not be enough to separate them clearly. In this case instead of a single
s-sidebarwidget--content element with multile items, use multiple
s-sidebarwidget--content elements, which will be separated by subtle divider lines.
s-sidebarwidget--content, the other possible child class is
s-sidebarwidget--header, which unsurprisingly creates a header. Headers can be used both as a title for the widget, as well as to create several sections inside the widget.
s-sidebarwidget__small-bold-text modifier is available for headers to modify the text appearance.
Three modifier classes are available for changing the background color of an
A common use for sidebar widgets is as a navigation block or table of contents, including a highlight of the page that the user is currently looking at.
The recommended pattern, as shown in the example below, is to make the
nav element, and for each group of links to create a
ul with the classes
s-sidebarwidget--content s-sidebarwidget__items, within which each
li is of class
The currently active navigation item should have the
aria-current attribute set to
"page" (if it is a direct link to the very page that the user is looking at) or
"true" (in all other cases, e.g. if it is a link to a page that is conceptually a parent or the current page). This
aria-current attribute can be on the
li or on the
If you have a second level of navigation, you can add a
ul of class
-subnav to the top-level item. Highlighting the currently active navigation is a little more constrained in this case:
If the currently active top-level element has a subnavigation, the top-level
aria-current must be on the
a, not the
The currently active second-level element must have its
aria-current on the
li, not the
There is often a need for a header to contain a link or link-like clickable that refers to the whole widget or to the section that this header starts. We call this an “action link”, and it’s created by adding the class
This link must come before the header text, otherwise it will not be placed correctly should the header ever wrap to multiple lines.
In order to create an accordion, i.e. to make part of the sidebar widget expandable / collapsible, you can make use of the
s-sidebarwidget-header element that controls the accordion needs a modifier class of
s-sidebarwidget__expanding-control in order to display the expander arrow. Beyond that, it needs all the attributes as described for the controlling button in the expandable documentation.
The (one or more) content elements that are meant to be collapsed must be wrapped in the
s-expandable element; inside this wrapper element there is the
s-expandable--content. This can be the same element as the
s-sidebarwidget--content element (if there’s only one content element that is meant to be collapsed), or it can be an additional wrapper element around the content element(s).