Box is a module for creating rounded-corner boxes with a white background and gray borders. Box has optional element styles for headers, lists, and footers.
This repository is a module of the full primer repository.
$ npm install --save primer-box
The source files included are written in Sass (
scss) You can simply point your sass
include-path at your
node_modules directory and import it like this.
You can also import specific portions of the module by importing those partials from the
/lib/ folder. Make sure you import any requirements along with the modules.
For a compiled css version of this module, a npm script is included that will output a css version to
build/build.css The built css file is also included in the npm package.
$ npm run build
.Box component can be used for something as simple as a rounded corner box, or more complex lists and forms. It includes optional modifiers for padding density and color themes.
.Box is a container with a a white background, a light gray border, and rounded corners. By default there are no additional styles such as padding, these can be added as needed with utility classes. Other styles and layouts can be achieved with box elements and modifiers shown in the documentation below.
This is a box.
Box elements include
Box-footer. These elements include borders and consistent padding. Optionally, you can include use
Box-title which applies a bold font-weight the heading.
Box titleBox bodyBox footer
Box-row to add rows with borders and maintain the same padding. Box rows have a lighter border to give contrast between the header and footer.
Note: Box rows have some reliance on markup structure in order to target the first and last rows, therefore using an unordered list is recommended. See box row markup structure for more information.
Box row oneBox row twoBox row threeBox row four
Rows can be used with or without
Box headerBox bodyBox row oneBox row twoBox row threeBox row fourBox footer
Box rows have some reliance on markup structure in order to target the first and last rows. Box rows are given a top border that is lighter in color than other box elements so the first row is targeted to apply a darker border color. An inner border-radius is applied to the first and last rows that that row corners don't poke outside the
Box, this can be particularly noticeable when using a highlight on box rows.
Using an unordered list is recommended in order to target the first and last rows, however, if you need to use a
<div> for your rows, you may want to place your rows inside a parent
<div> so that the first and last rows are styled appropriately.
Box header<!-- This wrapping div ensures the first and last rows can be targeted for styling. -->Box row using a divBox row using a div
You can changed the padding density of the box component.
Box--condensed to apply a more condensed line-height and reduce the padding on the Y axis.
Box titleBox bodyBox row oneBox row twoBox footer
Box--spacious to increase padding and increase the title font size.
You may want to increase the overall font size to work with the larger padding, in this example the default body font size is increased to 16px using the
f4 typography utility.
Box titleBox bodyBox row oneBox row twoBox footer
Box--blue to style the box borders and box header in blue.
Box headerBox row oneBox row twoBox footer
Box-header--blue to add to change the header border and background to blue.
Box with blue headerBox body
Box--danger to apply a red border to the outside of the box. This theme is helpful for communicating destructive actions.
Box-danger only works with either
Row oneRow two
Box-danger is often paired with a red heading. See the subhead docs for more information.
Danger zoneBox body
You can change the background color for individual rows, or change the color on hover or navigation focus.
Box-row--focus-blue when using along-side
navigation-focus if you want to highlight rows when using keyboard commands.
.Box-row--focus-gray and .navigation-focus.Box-row--focus-gray.Box-row--focus-blue and .navigation-focus.Box-row--focus-blue
.Box-row-unread to apply a blue vertical line highlight for indicating a row contains unread items.
Box rowBox row unreadBox row
Box-row-link when you want a link to appear dark gray and blue on hover on desktop, and remain a blue link on mobile. This is useful to indicate links on mobile without having hover styles.
Box row link
border-dashed utility to apply a dashed border to a box.
A box with a dashed border
flash-full for flash alert inside a box to remove the rounded corners. Place the flash alert above the
Box-body and underneath the
Flash alerts come in three different colors and can be used with icons and buttons, see the alert documentation for more information.
Box header<%= octicon "x" %>Flash message with close button.<%= octicon("check") %> Flash success with an icon.<%= octicon("alert") %> Flash warning with an icon.Flash error inside a Box.Box body
btn-octicon when you want the icon to maintain the same padding as other box elements. This selector offsets margin to ensure it lines up on the left and right sides of the box so you may need to add padding neighboring elements.
Box body<%= octicon("pencil") %>
It's common to want to float icons to the far left or right and stop the
Box-titlefrom wrapping underneath. To do this you'll need to create a media object with utilities. Add
clearfix to the surrounding div (this could be the header, body, or rows), add
overflow-hidden to the title (or other text element), and float the icons as desired.
<%= octicon("x") %>A very long title that wraps onto multiple lines without overlapping or wrapping underneath the icon to it's rightBox body
<%= octicon "check" %>A very long paragraph that wraps onto multiple lines without overlapping or wrapping underneath the icon to it's left
Use a counter with a background that works against the contrast of the box header. The default counter colors do not stand out well against the header background so we suggest using one of the following styles:
Counter--gray for a counter with a gray background and dark gray text.
Box title12Box body
Counter--gray-dark for a counter with a dark gray background and white text.
Box title12Box body
To achieve different layouts when adding buttons or form elements to boxes we suggest you use utilities to achieve the layout you want. Here's some common examples:
Use flexbox utilities to center align items, and avoid using floats by using
flex-auto to have the text fill the remaining space so that the button rests on the far right.
Box titleButtonBox body
A similar approach can be used for buttons with multiple lines of text within a row.
Row titleDescriptionViewRow titleDescriptionViewRow titleDescriptionView
Using flexbox along with form, button, and link styles, you can create more complex box headers for things like bulk actions and sorting.
Check itSelect menuBox body
You can put forms in boxes. Often form submission buttons are aligned to the bottom right of the form which you can do with
text-right instead of using floats.
Example form titleExample labelYes pleaseCancelSubmit
When a box is all by itself centered on a page you can use column widths to control the width of the box. If needed, break the mold a little and use typography utilities instead of the built in box title styles.
Example formExample labelSubmit
Box patterns can also be made with, and modified with border utilities.