Components

Updated: May 4, 2025

Once UI components are prop-based, customizable, and built for real-world usage in modern apps. They aim to balance expressiveness with clarity—avoiding over-abstraction while supporting flexibility and scalability.

Boilerplate

Use the following boilerplate to build Once UI components:

Boilerplate

"use client";

import React, { useState, useEffect, forwardRef } from "react";
import classNames from "classnames";
import styles from "./Component.module.scss";
import { Flex } from "@once-ui-system/core";

interface ComponentProps extends React.ComponentProps<typeof Flex> {
  children: React.ReactNode;
  className?: string;
  style?: React.CSSProperties;
}

const Component = forwardRef<HTMLDivElement, ComponentProps>(
  ({ children, className, style, ...rest }, ref) => {
    const [loading, setLoading] = useState(false);

    useEffect(() => {
      // Optional interactivity
    }, []);

    return (
      <Flex
        ref={ref}
        style={style}
        className={classNames(styles.component, className)}
        {...rest}
      >
        {children}
      </Flex>
    );
  }
);

Component.displayName = "Component";
export { Component };

Principles

No over-abstraction — components favor simplicity over excessive composition
Named exports only — components are always exported as export { Component }
Consistent naming
- displayName matches the filename
- Filenames are PascalCase (e.g. CursorCard.tsx)
State conventions
- Use loading instead of isLoading, open instead of isOpen
- The exception is a name the DOM already declares on the element the component renders. checked, prefix and size are all inherited from React's HTML attribute types, so a component that wants them must Omit the inherited one and redeclare — as Checkbox, Input and Textarea do. Never reach for an is/has prefix to dodge the collision; that is what produced isChecked, hasPrefix and the height-that-meant-size before 2.0
- Boolean props that toggle visibility read showX (showLabel, showIcon), so the unprefixed name stays free for the thing itself
Layout primitives
- Structure built with Flex and Grid
- Interactive styles live in *.module.scss
Client behavior
- Use "use client" in any component using hooks or state
Class names
- Use classNames() to merge static and dynamic classes
Children-first
- Props like children are encouraged for flexibility

Interactivity

Use ElementType to dynamically render:
- <a>, <button>, NextLink, or layout primitives like Flex
External links automatically include rel="noopener noreferrer"

Composition

Use forwardRef for exposing ref
Spread Flex/Grid props onto the outer wrapper
Combine className and style props cleanly
Prefer ReactNode over strings for flexibility and slot-style APIs

BasicsBreakpoints

Edit this page on GitHub

Built with curiosity by Lorant One and the Design Engineers Club