Styling

Introduction

Hopper components are designed to be consistent across all Workleap applications. They include built-in styling that has been considered carefully, and extensively tested. In general, customizing Hopper is discouraged, but most components do offer control over layout and other aspects. In addition, you can use Hopper's tokens to ensure your application conforms to design requirements, and is adaptive across color schemes.

Style props

A Hopper style property is a mapping of a CSS property to a component property. With style props, Hopper let you easily set style values for a curated set of CSS properties like font-size, margin, padding, width and many more.

All of the available style props are listed in the "Properties List" section below.

Usage

To use a style prop on a Hopper component, pass the prop as a camelCased string to the component. By default, only tokens are accepted as values for style props. They help promote consistency and maintainability across your application.

If you need to pass a custom value, you can use the UNSAFE_ prefix to bypass the token system. You can refer to the "Escape hatches" section for more information.

Shorthands

Props like border and paddingX are also provided to help you save keystrokes. An exhaustive list of all the supported props is available in the "Properties List" section.

Responsive styles

All style props support responsive values. You can pass an object with breakpoints as keys and values as values to a style prop to set different values for different breakpoints. More information is available in the Responsive Styles article.

Escape hatches

While we encourage teams to utilize Hopper styles as it is, we do realize that sometimes product specific customizations may be needed. In these cases, we encourage you or your designers to talk to us. We may be able to suggest an alternative implementation strategy, or perhaps your design can help inform future Hopper additions.

While the traditional className and style props are always supported in Hopper components, we also provide an escape hatch for passing custom values to style props. This is done by prefixing the prop name with UNSAFE_.

The UNSAFE_ prefix might look scary, but it's there to remind you that you're bypassing the token system. It's a way to ensure that you're aware that you're doing something that might not be automatically updated when tokens change. It will also help you to search for these usages when you want to update them, or help us to provide missing tokens.

Pseudo-classes

Style props doesn't support every CSS pseudo-classes. Location pseudo-classes, input pseudo-classes, tree-structural pseudo-classes, ::before and ::after are not supported and will most likely never be.

When a CSS pseudo-class is not supported by Hopper style props, we recommend using a CSS class.

Since the following user action pseudo-classes are often used, some style props support them. These behaves like their pseudo CSS counterparts.

Not all style props support user action pseudo-classes. Find out which props support user action pseudo-classes in the "Properties List" section.

HTML Elements

You might wonder how to use Hopper style props on your HTML elements?

Hopper provides a set of HTML element components already configured with Hopper styled system. You should choose these components over native HTML elements.

<A>, <Address>, <Article>, <Aside>, <HtmlButton>, <Div>, <HtmlFooter>, <HtmlHeader>, <Img>, <Input>, <List>, <Main>, <Nav>, <Section>, <Span>, <Table>

For text elements, prefer a <Text> or <Paragraph> component rather than <Span> or a <Div>.

Custom components

Sometimes, you may find yourself needing to build a component that doesn't exist in Hopper, but this component would benefit from using Hopper's style props.

There are 2 ways to build a custom component with Hopper style properties, as seen below:

HTML Element

Instead of using a native HTML element to create your component, you can use one of the Hopper HTML Element components. This way, you can simply forward the style props to the component.

This is an example using a Div, but you can use any of the HTML Element components.

useStyledSystem

If you need to build a more complex component, you can use the useStyledSystem function. This function allows you to create a custom component with Hopper style props.

The useStyledSystem function returns a stylingProps object containing a resulting style object and a className. You can then spread the stylingProps object on your component, or merge them with your existing className and style properties.

We don't automatically merge the className and style props because most of the className and style props in Hopper also accept a function.

Properties List

The following tables provide a list of all available style props by category.

Space

<Div padding="inset-md">
    Hopper
</Div>

Color

<Div backgroundColor="primary-weak" color="neutral">
    Hopper
</Div>

Typography

<Header letterSpacing="0.3rem">Hopper</Header>

Layout

<Div UNSAFE_width="30rem">
    Hopper
</Div>

Flex Layout

<Div alignItems="center">
    <Text>Tree frog</Text>
    <Text>Pond frog</Text>
</Div>

Grid Layout

<Div gridAutoFlow="row dense">
    <Text>Tree frog</Text>
    <Text>Pond frog</Text>
</Div>

Background

<Div
  backgroundImage="url('/images/dog.png')"
  backgroundPosition="center"
  backgroundRepeat="no-repeat"
/>

Border

<Div
    border="primary"
    borderRadius="rounded-md"
>
    Tree frog
</Div>

Border props (border, borderBottom, borderTop, borderRight, borderLeft) uses an implicit style (solid) and width(1px). These properties only accepts colors for value.

Position

<Div
    top="12px"
    position="absolute"
/>

Shadow

<Div
    boxShadow="lifted"
/>

Miscellaneous