Skip to content

System arguments

All Primer ViewComponents accept a standard set of options called system arguments, mimicking the styled-system API used by Primer React.

Under the hood, system arguments are mapped to Primer CSS classes, with any remaining options passed to Rails' content_tag.

Responsive values

To apply different values across responsive breakpoints, pass an array with up to five values in the order [default, small, medium, large, xlarge]. To skip a breakpoint, pass nil.

For example:

<%= render Primer::HeadingComponent.new(mt: [0, nil, nil, 4, 2]) do %>
Hello world
<% end %>

Renders:

<h1 class="mt-0 mt-lg-4 mt-xl-2">Hello world</h1>

HTML attributes

System arguments include most HTML attributes. For example:

NameTypeDescription
ariaHashAria attributes: aria: { label: "foo" } renders aria-label='foo'.
dataHashData attributes: data: { foo: :bar } renders data-foo='bar'.
heightIntegerHeight.
hiddenBooleanWhether to assign the hidden attribute.
styleStringInline styles.
titleStringThe title attribute.
widthIntegerWidth.

Animation

NameTypeDescription
animationSymbolOne of :fade_down, :fade_in, :fade_out, :fade_up, :grow_x, :hover_grow, :pulse, :pulse_in, :rotate, :scale_in, or :shrink_x.

Border

NameTypeDescription
border_bottomIntegerSet to 0 to remove the bottom border.
border_leftIntegerSet to 0 to remove the left border.
border_radiusIntegerOne of 0, 1, 2, or 3.
border_rightIntegerSet to 0 to remove the right border.
border_topIntegerSet to 0 to remove the top border.
borderSymbolOne of :bottom, :left, :right, :top, :x, :y, or true.
box_shadowBoolean, SymbolBox shadow. One of :extra_large, :large, :medium, :none, or true.

Color

NameTypeDescription
bgSymbolBackground color. One of :accent, :accent_emphasis, :attention, :attention_emphasis, :canvas, :canvas_inset, :canvas_inverse, :danger, :danger_emphasis, :danger_inverse, :default, :done, :done_emphasis, :emphasis, :info, :info_inverse, :inset, :overlay, :primary, :secondary, :severe, :severe_emphasis, :sponsors, :sponsors_emphasis, :subtle, :success, :success_emphasis, :success_inverse, :tertiary, :warning, or :warning_inverse.
border_colorSymbolBorder color. One of :accent, :accent_emphasis, :attention, :attention_emphasis, :danger, :danger_emphasis, :default, :done, :done_emphasis, :info, :inverse, :muted, :primary, :secondary, :severe, :severe_emphasis, :sponsors, :sponsors_emphasis, :subtle, :success, :success_emphasis, :tertiary, or :warning.
colorSymbolText color. One of :accent, :attention, :danger, :default, :done, :icon_danger, :icon_info, :icon_primary, :icon_secondary, :icon_success, :icon_tertiary, :icon_warning, :inherit, :muted, :on_emphasis, :severe, :sponsors, :subtle, :success, :text_danger, :text_inverse, :text_link, :text_primary, :text_secondary, :text_success, :text_tertiary, :text_warning, or :text_white.

Flex

NameTypeDescription
align_itemsSymbolOne of :baseline, :center, :flex_end, :flex_start, or :stretch.
align_selfSymbolOne of :auto, :baseline, :center, :end, :start, or :stretch.
directionSymbolOne of :column, :column_reverse, :row, or :row_reverse.
flexInteger, SymbolOne of 1 and :auto.
flex_growIntegerTo enable, set to 0.
flex_shrinkIntegerTo enable, set to 0.
flex_wrapSymbolOne of :nowrap, :reverse, or :wrap.
justify_contentSymbolOne of :center, :flex_end, :flex_start, :space_around, or :space_between.

Grid

NameTypeDescription
clearfixBooleanWether to assign the clearfix class.
colIntegerNumber of columns. One of 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, or 12.
containerSymbolSize of the container. One of :lg, :md, :sm, or :xl.

Layout

NameTypeDescription
displaySymbolOne of :block, :flex, :inline, :inline_block, :inline_flex, :none, :table, or :table_cell.
wSymbolOne of :auto, :fit, or :full.
hSymbolOne of :fit and :full.
hideSymbolHide the element at a specific breakpoint. One of :lg, :md, :sm, or :xl.
visibilitySymbolVisibility. One of :hidden and :visible.
vertical_alignSymbolOne of :baseline, :bottom, :middle, :text_bottom, :text_top, or :top.

Position

NameTypeDescription
bottomBooleanIf false, sets bottom: 0.
floatSymbolOne of :left, :none, or :right.
leftBooleanIf false, sets left: 0.
positionSymbolOne of :absolute, :fixed, :relative, :static, or :sticky.
rightBooleanIf false, sets right: 0.
topBooleanIf false, sets top: 0.

Spacing

NameTypeDescription
mIntegerMargin. One of 0, 1, 2, 3, 4, 5, 6, or :auto.
mbIntegerMargin bottom. One of -12, -11, -10, -9, -8, -7, -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, or :auto.
mlIntegerMargin left. One of -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, or :auto.
mrIntegerMargin right. One of -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, or :auto.
mtIntegerMargin top. One of -12, -11, -10, -9, -8, -7, -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, or :auto.
mxIntegerHorizontal margins. One of 0, 1, 2, 3, 4, 5, 6, or :auto.
myIntegerVertical margins. One of 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, or 12.
pIntegerPadding. One of 0, 1, 2, 3, 4, 5, 6, or :responsive.
pbIntegerPadding bottom. One of 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, or 12.
plIntegerPadding left. One of 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, or 12.
prIntegerPadding right. One of 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, or 12.
ptIntegerPadding left. One of 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, or 12.
pxIntegerHorizontal padding. One of 0, 1, 2, 3, 4, 5, or 6.
pyIntegerVertical padding. One of 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, or 12.

Typography

NameTypeDescription
font_familySymbolFont weight. One of :mono.
font_sizeString, Integer, SymbolOne of 0, 1, 2, 3, 4, 5, 6, 00, :normal, or :small.
font_styleSymbolFont weight. One of :italic.
font_weightSymbolFont weight. One of :bold, :emphasized, :light, or :normal.
text_alignSymbolText alignment. One of :center, :left, or :right.
text_transformSymbolText alignment. One of :uppercase.
underlineBooleanWhether text should be underlined.
word_breakSymbolWhether to break words on line breaks. One of :break_all and :break_word.

Other

NameTypeDescription
classesStringCSS class name value to be concatenated with generated Primer CSS classes.
test_selectorStringAdds data-test-selector='given value' in non-Production environments for testing purposes.