Base Component

Component creation starts in the @qui/base package. Each component is located in a directory within src/components

base

src

components

alert

button

etc...

Guidelines

TIP

Each component starts with the q- prefix to distinguish it from external modules. This has the added benefit of avoiding reserved HTML elements like button and link.

Example Component

We'll use the existing Tag component for this example.

components

tag

index.ts

q-tag.classes.ts

q-tag.scss

q-tag.types.ts

Unpacking the above:

q-tag.classes.ts: Utility class used to compute consistent CSS class names for each of the supported frameworks.
q-tag.scss: Component CSS. Note: when the @qui/base package runs build or watch, all scss files are collected, processed, and minified into dist/all.min.css.
q-tag.types.ts: TypeScript definitions for the component's input properties.
index.ts: barrel file.

`q-tag.types.ts`

// each property is prefixed with the name of the component (QTag)
export type QTagSize = "s" | "m" | "l"

`q-tag.classes.ts`

import {clsx} from "../../utilities"

import {QTagSize} from "./q-tag.types"

export class QTagClasses {
  static root(
    size: QTagSize,
    checked: boolean,
    readonly: boolean,
    disabled: boolean,
    stretch: boolean,
  ) {
    return clsx("q-tag--root", `q-size-${size ?? "m"}`, {
      "q-checked": checked,
      "q-disabled": disabled,
      "q-readonly": readonly,
      "q-stretch": stretch,
    })
  }

  static closeIcon() {
    return clsx("q-tag--close-icon")
  }

  static label() {
    return clsx("q-tag--label")
  }
}

`q-tag.scss`

Omitted for the sake of brevity. Refer to the file in the repository.

`index.ts`

// barrel file
export * from "./q-tag.classes.ts"
export * from "./q-tag.types.ts"

Key Takeaways

If a component has one or more nested elements, it should have a utility class like the above that generates common CSS class names. Most components will have a utility class.
Most components will have input attributes, but some components may not. You can leave out the .types file in the latter case.

With the base package covered, let's create the corresponding React component.

Component Authoring

React Component