Concepts
System Props
System props apply standard sets of properties to a component that can be used to alter its appearance on the fly.
System props are paired with values from Balance’s palette in order to apply
custom styles to components. In the following example, the critical
color is
being applied to the Text
component.
- The system prop (
color
in this case) matches up to thecolor
CSS property, and the theme value is from thetext
category of our palette. - The system prop (
marginTop
in this case) matches up to themargin-top
CSS property, and the theme value is from thespacing
category of our theme.
Many components in Balance are given access to certain groups of system props,
depending on the needs of that component. Most components have access to the
spacing
group, which gives the component access to props that control margin
and padding.
Responsive values
When a single theme value is given to a system prop, that value will be applied at every screen size. When an array of values is given, those values will be distributed across the breakpoints specified in the current theme.
Note that if a value is repeated across several breakpoints, a null
value can be
used to prevent generating unnecessary CSS.
The “as” prop
Most components in Balance accept the as
prop, which allows the consumer to
change the root element that the component renders.
For instance, <Box as="span" />
would render the Box component as a span
tag
instead of its default (in this case, div
).
Important: Changing the root element can affect the styles and accessibility of
a component. Use common sense when specifying the as
prop — try to use HTML
elements that are related to the existing root element of the component. For
example, if a component normally renders a div
tag, don’t try to change it to
something like a table
.
Forwarding refs
React.forwardRef
is re-exported from @reckon-web/utils
as forwardRefWithAs
with different type definitions to work with components that have an as
prop.
It accepts two type arguments, DefaultElementType
and Props
.
import { forwardRefWithAs } from '@reckon-web/utils';type Props = { color: string;};let Button = forwardRefWithAs<'button', Props>( ({ color, as: Tag = 'button', ...props }, ref) => { return <Tag css={{ color }} ref={ref} {...props} />; });