System props

All of the components in Blockstack UI are built with styled-components and implement styled-system. With this, you can pass css attributes to any component as props. Check out the page further reading to dig deeper.

System props reference

See below for the various props and aliases you can pass for styling components. You can see the full spec on the Styled System docs.

Margin & padding

import
{
Box
}
from
'@blockstack/ui'
;
// m={2} refers to the value of `theme.space[2]`
<
Box
m
=
{
2
}
>
Tomato
</
Box
>
;
// You can also use custom values
<
Box
maxW
=
"
960px
"
mx
=
"
auto
"
/>
;
// sets margin `8px` on all viewports and `16px` from the first breakpoint and up
<
Box
m
=
{
[
2
,
3
]
}
/>
;
PropCSS PropertyTheme Key
m, marginmarginspace
mt, marginTopmargin-topspace
mr, marginRightmargin-rightspace
mb, marginBottommargin-bottomspace
ml, marginLeftmargin-leftspace
mxmargin-left and margin-rightspace
mymargin-top and margin-bottomspace
p, paddingpaddingspace
pt, paddingToppadding-topspace
pr, paddingRightpadding-rightspace
pb, paddingBottompadding-bottomspace
pl, paddingLeftpadding-leftspace
pxpadding-left and padding-rightspace
pypadding-top and padding-bottomspace

Color & background color

import
{
Box
}
from
"@blockstack/ui"
;
// picks up a nested color value using dot notation
// => `theme.colors.ink[50]`
<
Box
color
=
'
ink.50
'
/>
// raw CSS color value
<
Box
color
=
'
#f00
'
/>
// background colors
<
Box
bg
=
'
tomato
'
/>
// verbose prop
<
Box
backgroundColor
=
'
tomato
'
/>
PropCSS PropertyTheme Key
colorcolorcolors
bg, backgroundColorbackground-colorcolors
opacityopacitynone

Typography

import
{
Text
}
from
"@blockstack/ui"
;
// font-size of `theme.textStyle.display.large
<
Text
text
Style
="
display.large
"
/>
// font-size `32px`
<
Text
fontSize
=
{
32
}
/>
// font-size `'2em'`
<
Text
fontSize
=
'
2em
'
/>
// text-align `left` on all viewports and `center` from the first breakpoint and up
<
Text
textAlign
=
{
[
'left'
,
'center'
]
}
/>
PropCSS PropertyTheme Key
fontFamilyfont-familyfonts
fontSizefont-sizefontSizes
fontWeightfont-weightfontWeights
lineHeightline-heightlineHeights
letterSpacingletter-spacingletterSpacings
textAligntext-alignnone
fontStylefont-stylenone
textTransformtext-transformnone
textDecorationtext-decorationnone

Layout, width and height

import
{
Box
}
from
"@blockstack/ui"
;
// verbose
<
Box
width
=
"
100%
"
height
=
{
32
}
/>
;
// shorthand
<
Box
w
=
"
100%
"
h
=
"
32px
"
/>
;
// width `50%`
<
Box
w
=
{
1
/
2
}
/>
// width `256px`
<
Box
w
=
{
256
}
/>
// width `'40px'`
<
Box
w
=
'
40px
'
/>
PropCSS PropertyTheme Key
w, widthwidthsizes
h, heightheightsizes
minW, minWidthmin-widthsizes
maxW, maxWidthmax-widthsizes
minH, minHeightmin-heightsizes
maxH, maxHeightmax-heightsizes
d, displaydisplaynone
sizewidth heightsizes
verticalAlignvertical-alignnone
overflowoverflownone
overflowXoverflowXnone
overflowYoverflowYnone

Flexbox

import
{
Box
,
Flex
}
from
'@blockstack/ui'
;
// verbose
<
Box
display
=
"
flex
"
alignItems
=
"
center
"
justifyContent
=
"
space-between
"
>
Box
with
Flex props
</
Box
>
;
// shorthand using the `Flex` component
<
Flex
align
=
"
center
"
justify
=
"
center
"
>
Flex Container
</
Flex
>
;

Note: Props in * will only work if you use the Flex component.

PropCSS PropertyTheme Key
alignItems, *alignalign-itemsnone
alignContentalign-contentnone
justifyItemsjustify-itemsnone
justifyContent, *justifyjustify-contentnone
flexWrap, *wrapflex-wrapnone
flexDirection, flexDir, *directionflex-directionnone
flexflex (shorthand)none
flexGrowflex-grownone
flexShrinkflex-shrinknone
flexBasisflex-basisnone
justifySelfjustify-selfnone
alignSelfalign-selfnone
orderordernone

Grid Layout

import
{
Box
,
Grid
}
from
'@blockstack/ui'
;
// verbose
<
Box
display
=
"
grid
"
gridGap
=
{
2
}
gridAutoFlow
=
"
row dense
"
>
Grid
</
Box
>
;
// shorthand using the `Grid` component
<
Grid
gap
=
{
2
}
autoFlow
=
"
row dense
"
>
Grid
</
Grid
>
;

Note: Props in * will only work if you use the Grid component.

PropCSS PropertyTheme Key
gridGap, *gapgrid-gapspace
gridRowGap, *rowGapgrid-row-gapspace
gridColumnGap, *columnGapgrid-column-gapspace
gridColumn, *columngrid-columnnone
gridRow, *rowgrid-rownone
gridArea, *areagrid-areanone
gridAutoFlow, *autoFlowgrid-auto-flownone
gridAutoRows, *autoRowsgrid-auto-rowsnone
gridAutoColumns, *autoColumnsgrid-auto-columnsnone
gridTemplateRows, *templateRowsgrid-template-rowsnone
gridTemplateColumns, *templateColumnsgrid-template-columnsnone
gridTemplateAreas, *templateAreasgrid-template-areasnone

Background

import
{
Box
}
from
'@blockstack/ui'
;
// verbose
<
Box
backgroundImage
=
"
url('/images/kitten.png')
"
backgroundPosition
=
"
center
"
backgroundRepeat
=
"
no-repeat
"
/>
;
// shorthand
<
Box
bgImage
=
"
url('/images/puppy.png')
"
bgPos
=
"
center
"
bgRepeat
=
"
no-repeat
"
/>
;
PropCSS PropertyTheme Key
backgroundbackgroundnone
bgImg, backgroundImagebackground-imagenone
bgSize, backgroundSizebackground-sizenone
bgPos,backgroundPositionbackground-positionnone
bgRepeat,backgroundRepeatbackground-repeatnone
bgAttachment,backgroundAttachmentbackground-attachmentnone

Borders

import
{
Box
}
from
'@blockstack/ui'
;
<
Box
border
=
"
1px
"
borderRadius
=
"
6px
"
borderColor
=
"
ink.i00
"
>
Card
</
Box
>
;
PropCSS PropertyTheme Field
borderborderborders
borderWidthborder-widthborderWidths
borderStyleborder-styleborderStyles
borderColorborder-colorcolors
borderTopborder-topborders
borderTopWidthborder-top-widthborderWidths
borderTopStyleborder-top-styleborderStyles
borderTopColorborder-top-colorcolors
borderRightborder-rightborders
borderRightWidthborder-right-widthborderWidths
borderRightStyleborder-right-styleborderStyles
borderRightColorborder-right-colorcolors
borderBottomborder-bottomborders
borderBottomWidthborder-bottom-widthborderWidths
borderBottomStyleborder-bottom-styleborderStyles
borderBottomColorborder-bottom-colorcolors
borderLeftborder-leftborders
borderLeftWidthborder-left-widthborderWidths
borderLeftStyleborder-left-styleborderStyles
borderLeftColorborder-left-colorcolors
borderXborder-left & border-rightborders
borderYborder-top & border-bottomborders

Border Radius

import
{
Button
}
from
'@blockstack/ui'
;
// This button will have no right borderRadius
<
Button
roundedRight
=
"
0
"
>
Button
1
</
Button
>
;
// This button will have no left borderRadius*/
<
Button
roundedLeft
=
"
0
"
>
Button
2
</
Button
>
;
// top left and top right radius will be `theme.radii.md` => 4px
<
Button
roundedTop
=
"
md
"
>
Button
2
</
Button
>
;
PropCSS PropertyTheme Field
rounded, borderRadiusborder-radiusradii
roundedTopLeft, borderTopLeftRadiusborder-top-left-radiusradii
roundedTopRight, borderTopRightRadiusborder-top-right-radiusradii
roundedBottomRight, borderBottomRightRadiusborder-bottom-right-radiusradii
roundedBottomLeft, borderBottomLeftRadiusborder-bottom-left-radiusradii
roundedTopborder-top-left-radius & border-top-right-radiusradii
roundedRightborder-top-right-radius & border-bottom-right-radiusradii
roundedBottomborder-bottom-left-radius & border-bottom-right-radiusradii
roundedLeftborder-top-left-radius & border-bottom-left-radiusradii

Position

import
{
Box
}
from
'@blockstack/ui'
;
// verbose
<
Box
position
=
"
absolute
"
>
Cover
</
Box
>
;
// shorthand
<
Box
pos
=
"
absolute
"
>
Cover
</
Box
>
;
<
Box
pos
=
"
absolute
"
top
=
"
0
"
left
=
"
0
"
>
Absolute
with
top and left
</
Box
>
;
<
Box
pos
=
"
fixed
"
w
=
"
100%
"
zIndex
=
{
2
}
>
Fixed
with
zIndex
</
Box
>
;
PropCSS PropertyTheme Field
pos,positionpositionnone
zIndexz-indexzIndices
toptopspace
rightrightspace
bottombottomspace
leftleftspace

Shadow

import
{
Box
,
Text
}
from
'@blockstack/ui'
;
// text-shadow will be `theme.shadows.low`
// box-shadow will be `theme.shadows.high`
<
Box
textShadow
=
"
low
"
boxShadow
=
"
high
"
/>
;
// raw CSS values
<
Text
textShadow
=
"
0px 1px 2px rgba(0, 0, 0, 0.04)
"
boxShadow
=
"
0px 8px 16px rgba(27, 39, 51, 0.08)
"
>
Text
with
shadows
</
Text
>
;
PropCSS PropertyTheme Field
textShadowtext-shadowshadows
shadow,boxShadowbox-shadowshadows

Other Props

Asides all the common system props listed above, all component will accept the following props:

PropCSS PropertyTheme Field
animationanimationnone
appearanceappearancenone
transformtransformnone
transformOrigintransform-originnone
visibilityvisibilitynone
whiteSpacewhite-spacenone
userSelectuser-selectnone
pointerEventspointer-eventsnone
wordBreakword-breaknone
overflowWrapoverflow-wrapnone
textOverflowtext-overflownone
boxSizingbox-sizingnone
cursorcursornone
resizeresizenone
transitiontransitionnone
objectFitobject-fitnone
objectPositionobject-positionnone
objectPositionobject-positionnone
fillfillcolors
strokestrokecolors
outlineoutlinenone

The as prop

The as prop is a feature that all of our components get from styled-components. It allows you to pass a HTML tag or another component to a Blockstack UI component to be rendered as the base tag of that component along with all it's styles and props.

For example, say you are using a Button component, and you need to make it a link instead. You can compose a and Button like this:

Preview
Editable example

This allows you to use all of the Button props and all of the <a> props without having to wrap the Button in an a component.

Note: this does have some limitations.

Let's say you wanted the button to take styles from a Flex primitive. You'd do the following:

Preview
This is now using a Flex as the primary wrapper component.
Editable example

The issue with this, though, is the Button no long renders as a button DOM element. It will be rendered as a div because Flex by default renders as a div.

For these reasons, it's recommended only to use the as prop when you cannot achieve the same result by nesting components. The Flex / Button example could be done like so:

Preview
Editable example

or

Preview
Editable example