Styling

Style props

KeystarUI components support a limited set of styling options, including layout, spacing, sizing, and positioning options.

Patterns

While internal component styles such as padding, colors, borders and text styles are not available to override, external styles like margins and layout relationships can be set on most components.

The above example illustrates some common patterns:

• •
  Layout primitives like Flex accept common style props in addition to their own specific API.
• •
  Prefer keys from the token schema e.g. padding="small" for spacing and dimension props. CSS unit values are allowed e.g. width={120} but should be used scarcely.
• •
  Only logical properties e.g. insetEnd (instead of insetRight) are supported for direction-relative props corresponding to the horizontal plane.

Responsive props

Style props support responsive syntax to specify different values for the prop depending on the breakpoint. Breakpoints are mobile-first and correspond to common device resolutions.

mobile: 0 # essentially the “base”, influences all above
tablet: 768
desktop: 1280
wide: 1768 # target exceptionally wide viewports, which may undermine proximity relationships

In this example, the Notice has styles applied at the desktop breakpoint. Resize your browser window to see this in action.

Breakpoints are mobile first, which means style props apply at that breakpoint and above. For example, the "desktop" breakpoint is applied at screen sizes 1280px and wider. The "mobile" value should be used to specify the layout at the smallest possible screen size, and additional breakpoints may be added to adapt the layout for larger devices.

Conditional visibility

Conditionally toggle the visibility of components depending on the width of the viewport. The isHidden style prop provides a convenient above/below syntax for most cases.

Logical properties

CSS Logical Properties and Values is a module of CSS introducing logical properties and values that provide the ability to control layout through logical, rather than physical, direction and dimension mappings.

KeystarUI’s style props employ logical property syntax for inline, but not block properties. For example marginLeft is instead marginStart, which means everything just works for RTL languages.

Reference

Most components support the following style props.

Spacing

Sizing

Layout

Positioning

Custom components

Sometimes, you may find yourself needing to build a component that doesn’t exist in the component library.

The “box” primitive

A general purpose low-level primitive with no specific semantics that can be used for styling. In addition to the above style props, the Box accepts a suite of props for customising the appearance of an element.

The layout and typographic primitives, along with many other components, are built with Boxes.

Element type

By default, Box renders a div element. You can customise this using the elementType prop. Non-style props will be forwarded to the underlying element.

<Box elementType="span" id="element-type-example">
  ...
</Box>

Token schema

The tokenSchema object provides access to KeystarUI’s CSS variables, which can be used both within stylesheets and runtime code.

NOTE: You should only write custom CSS if you’re unable to use the Box primitive.

import { css, tokenSchema } from '@keystar/ui/style';

function SomeComponent(props) {
  return (
    <div
      className={css({
        padding: tokenSchema.size.space.large,
        // ...
      })}
      {...props}
    />
  );
}

Escape hatches

We encourage folks to use KeystarUI components “as is”, however we realise that sometimes customisations may be needed.

While the className and style props are not supported in KeystarUI components, there are two escape hatches that you can use at your own risk. These are UNSAFE_className and UNSAFE_style, which should be considered a last resort. They can be used to work around bugs or limitations in KeystarUI, but should not be employed long term.

The reasoning behind this is that future updates may cause unintended breaking changes in modified components. If the internal DOM structure or CSS properties of a KeystarUI component change, this may lead to conflicts with CSS overrides in your code. For this reason, className and style are unsafe, and if you use them know that you are doing so at your own risk.