@sys42/ui v3.1.0
System 42 UI
System 42 is a design system for building consistent and accessible web applications. This package contains components and styles that can easily be used in React applications.
Installation
npm install @sys42/ui
Usage
Styled React Components
Using the styled React components is the easiest way to work with System 42.
Every component imports an individual .css
file with default styles based on a set of CSS custom properties. You can make use of the exposed CSS custom properties to customize the look of the components.
You can find all available custom properties here: default-custom-properties.css
!NOTE If you need to customize the styles beyond the exposed custom properties, you should make use of the Base Hooks and style the components yourself. You can read more about using the Base Hooks in the Using the Base Hooks section.
The component styles depend on base.css
for CSS normalization and basic styles, and on default-custom-properties.css
for custom property defaults. To ensure these dependencies are met, import both base.css
and default-custom-properties.css
in your application.
All styles as well as the custom properties are inside a CSS Layer
named sys42
. The base styles, defined in base.css
, are inside a layer named sys42-base
.
Example
// Add these imports to your main file
import "@sys42/ui/base.css";
import "@sys42/ui/default-custom-properties.css";
import { Button, TextInput, Stack } from "@sys42/ui";
function App() {
return (
<Stack>
<TextInput placeholder="Type something" />
<Button>Click me</Button>
</Stack>
);
}
Using the Component Hooks
For all components, there are hooks available that can be used to change how the component is rendered. The hooks are named the same as the components but with a use
prefix. The main use case for the hooks is to change the element type of the component.
Simple Components
For simple components that render a single element, like a button, simply spread the returned elementProps
and attach the elementRef
to the element.
import { Link } from "react-router-dom";
import { createComponent, useButton } from "@sys42/ui";
export const ButtonLink = createComponent<ButtonProps, "a">("a", (hookOptions) => {
const { elementProps, elementRef } = useButton(hookOptions);
return <Link {...elementProps} ref={elementRef} />;
});
Complex Components
For more complex components that render multiple elements, you'll need to invoke an additional render function to handle the children. The hook will return a renderArgs
object, which must be passed to the render function. You can either use the default render function provided for each component or write your own.
import {
FormFieldProps,
createComponent,
useFormField,
renderFormField,
} from "@sys42/ui";
export const MyFormField = createComponent<FormFieldProps, "div">(
"div",
(hookOptions) => {
const { elementProps, elementRef, renderArgs } = useFormField(hookOptions);
return (
<div {...elementProps} ref={elementRef}>
{renderFormField(renderArgs)}
</div>
);
}
);
Using the Base Hooks
"In addition to React components and Component Hooks, the library provides Base Hooks for cases where you want to opt out of default styling.
Base Hooks don’t include any CSS and omit style-related props, such as the variant
prop in styled buttons. These hooks are prefixed with useBase…
and return everything needed to render the component.
For guidance on using Base Hooks, you can refer to the implementation of the corresponding Component Hook like useButton
.
Here’s a simple example of using a Base Hook to create a custom styled component:
import {
BaseFormFieldProps,
createComponent,
useBaseFormField,
renderFormField,
ExactProps,
} from "@sys42/ui";
import { cn } from "@sys42/utils";
type MyFormFieldProps = BaseFormFieldProps & {
myProp: boolean;
};
function useMyFormField<TTagName extends HTMLElementTagName>(
options: UseComponentOptions<MyFormFieldProps, TTagName>
) {
// The custom prop "myProp" is extracted from the props
const { myProp, ...baseProps } = options.props;
return useBaseFormField(
{
...options,
props: baseProps satisfies ExactProps<
BaseFormFieldProps,
MyFormFieldProps
>,
},
(draft) => {
// You can modify the formField here
draft.elementProps.className = cn(
draft.elementProps.className,
"my-form-field"
);
if (myProp) {
draft.elementProps.className += " my-form-field--my-prop";
}
draft.labelProps.className = cn(
draft.labelProps.className,
"my-form-field-label"
);
}
);
}
export const MyFormField = createComponent<MyFormFieldProps, "div">(
"div",
(hookOptions) => {
const { elementProps, elementRef, renderArgs } =
useMyFormField(hookOptions);
return (
<div {...elementProps} ref={elementRef}>
{renderFormField(renderArgs)}
</div>
);
}
);
Types
Read more about the types in the Type Strategy document.
Custom Properties
You can find all available custom properties here: default-custom-properties.css
All custom properties are prefixed with --sys42-
.
Overriding Styles
As all styles are in a CSS Layer named sys42
, you can easily override the styles by adding your own styles without a layer or in a layer with a higher priority.
If you want to overide styles globally, the easiest way is to do this by overriding custom properties. You can find a list of all available customer properties in the defaults file default-custom-properties.css
.
If you want to override styles for a specific occurence of a component, you can do this by adding a class to the component and then adding styles to this class.
Styling opinions
System 42 is built as a flexible design system, allowing you to customize it to suit your needs. However, it includes a few opinionated design choices:
Margin Top
Whenever margin
is used to create space between elements, margin-top
is preferred. The the CSS reset (which is base on normalize.css
) is extended and removes margin
for some elements.
For more information see this article.