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.

<Text color="critical" marginTop="large">
  Critical text
</Text>

1. The system prop (color in this case) matches up to the color CSS property, and the theme value is from the text category of our palette.
2. The system prop (marginTop in this case) matches up to the margin-top CSS property, and the theme value is from the spacing 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.

<Box
  background="dim"
  padding={['xsmall', 'small', 'medium', 'large', 'xlarge']}
>
  Responsive padding
</Box>

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} />;
  }
);