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
widthIntegerWidth.
heightIntegerHeight.
dataHashData attributes: data: { foo: :bar } renders data-foo='bar'.
ariaHashAria attributes: aria: { label: "foo" } renders aria-label='foo'.
titleStringThe title attribute.
hiddenBooleanWhether to assign the hidden attribute.

Arguments

NameTypeDescription
test_selectorStringAdds data-test-selector='given value' in non-Production environments for testing purposes.
mIntegerMargin. One of -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, or 6.
mtIntegerMargin left. One of -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, or 6.
mrIntegerMargin right. One of -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, or 6.
mbIntegerMargin bottom. One of -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, or 6.
mlIntegerMargin left. One of -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, or 6.
mxIntegerHorizontal margins. One of -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, 6, or :auto.
myIntegerVertical margins. One of -6, -5, -4, -3, -2, -1, 0, 1, 2, 3, 4, 5, or 6.
pIntegerPadding. One of 0, 1, 2, 3, 4, 5, or 6.
ptIntegerPadding left. One of 0, 1, 2, 3, 4, 5, or 6.
prIntegerPadding right. One of 0, 1, 2, 3, 4, 5, or 6.
pbIntegerPadding bottom. One of 0, 1, 2, 3, 4, 5, or 6.
plIntegerPadding left. One of 0, 1, 2, 3, 4, 5, or 6.
pxIntegerHorizontal padding. One of 0, 1, 2, 3, 4, 5, or 6.
pyIntegerVertical padding. One of 0, 1, 2, 3, 4, 5, or 6.
positionSymbolOne of :relative, :absolute, or :fixed.
topBooleanIf false, sets top: 0.
rightBooleanIf false, sets right: 0.
bottomBooleanIf false, sets bottom: 0.
leftBooleanIf false, sets left: 0.
displaySymbolOne of :block, :none, :inline, :inline_block, :table, or :table_cell.
vSymbolVisibility. One of :hidden and :visible.
hideSymbolHide the element at a specific breakpoint. One of :sm, :md, :lg, or :xl.
vertical_alignSymbolOne of :baseline, :top, :middle, :bottom, :text_top, or :text_bottom.
floatSymbolOne of :left and :right.
colIntegerNumber of columns.
underlineBooleanWhether text should be underlined.
colorSymbolText color. One of :blue, :red, :gray_light, :gray, :gray_dark, :green, :orange, :orange_light, :purple, :pink, :white, or :inherit. Note: this API is subject to change as we move to functional colors.
bgString, SymbolBackground color. Accepts either a hex value as a String or a color name as a Symbol.
box_shadowBoolean, SymbolBox shadow. One of true, :medium, :large, :extra_large, or :none.
borderSymbolOne of :left, :top, :bottom, :right, :y, or :x.
border_colorSymbolOne of :blue, :blue_light, :gray, :gray_dark, :green, :purple, :red, :red_light, :white, :yellow, or :black_fade. Note: this API is subject to change as we move to functional colors.
border_topIntegerSet to 0 to remove the top border.
border_bottomIntegerSet to 0 to remove the bottom border.
border_leftIntegerSet to 0 to remove the left border.
border_rightIntegerSet to 0 to remove the right border.
font_sizeString, IntegerOne of 00, 0, 1, 2, 3, 4, 5, or 6.
text_alignSymbolText alignment. One of :left, :right, or :center.
font_weightSymbolFont weight. One of :light, :normal, or :bold.
flexInteger, SymbolOne of 1 and :auto.
flex_growIntegerTo enable, set to 0.
flex_shrinkIntegerTo enable, set to 0.
align_selfSymbolOne of :auto, :start, :end, :center, :baseline, or :stretch.
justify_contentSymbolOne of :flex_start, :flex_end, :center, :space_between, or :space_around.
align_itemsSymbolOne of :flex_start, :flex_end, :center, :baseline, or :stretch.
widthSymbolOne of :fit and :fill.
heightSymbolOne of :fit and :fill.
word_breakSymbolWhether to break words on line breaks. Can only be :break_all.
tagSymbolHTML tag name to be passed to tag.send.
classesStringCSS class name value to be concatenated with generated Primer CSS classes.