STYLEGUIDE.md

Style guide

Import only React and use members from there instead of separate imports

// Good
import React from 'react';

// Bad
import React, { useState } from 'react';

// Bad
import * as React from 'react';

Use type instead of interface

// Good
export type AlertProps = { ... };

// Bad
export interface IAlertProps {}

Comment all props in multiline using jsdoc

// Good
export type AlertProps = {
  /**
   * Type of the alert.
   * @default 'informational'
   */
  type?: 'positive' | 'warning' | 'negative' | 'informational';
  ...

// Bad (single line)
export type AlertProps = {
  /** Type of the alert. */
  type?: 'positive' | 'warning' | 'negative' | 'informational';
  ...

// Bad (no comment at all)
export type AlertProps = {
  type?: 'positive' | 'warning' | 'negative' | 'informational';
  ...

Add description and example how to use the component

// Good

/**
 * A small box to quickly grab user attention and communicate a brief message.
 * @example
 * <Alert>This is a basic alert.</Alert>
 */
export const Alert = (props: AlertProps) => {
  ...

// Bad (no comments)

export const Alert = (props: AlertProps) => {
  ...

// Bad (no example)

/**
 * A small box to quickly grab user attention and communicate a brief message.
 */
export const Alert = (props: AlertProps) => {
  ...

Destruct props and set default values

// Good
export const Alert = (props: AlertProps) => {
  const {
    children,
    className,
    type = 'informational',
    clickableText,
    onClick,
    onClose,
    style,
    isSticky = false,
  } = props;
  ...

// Bad
export const Alert = ({
    children,
    className,
    type = 'informational',
    clickableText,
    onClick,
    onClose,
    style,
    isSticky = false,
  }: AlertProps) => {
  ...

Use classnames object syntax for conditional classes

// Good
<Button
  className={cx(
    'iui-button',
    { 'iui-invisible': styleType === 'borderless' },
    className,
  )}
  ...

// Bad (using short circuiting)
<Button
  className={cx(
    'iui-button',
    styleType === 'borderless' && 'iui-invisible',
    className,
  )}
  ...

Import individual icons directly from the cjs module

// Good
import SvgClose from '@itwin/itwinui-icons-react/cjs/icons/Close';
import SvgInfo from '@itwin/itwinui-icons-react/cjs/icons/Info';

// Bad (using barrel)
import { SvgClose } from '@itwin/itwinui-icons-react';

// Bad (using esm)
import SvgClose from '@itwin/itwinui-icons-react/esm/icons/Close';

// Bad (combining imports)
import { SvgClose, SvgInfo } from '@itwin/itwinui-icons-react/cjs/icons';

Use getDocument, getWindow instead of direct access

// Good
getWindow()?.clearTimeout(1);

// Good
getDocument()?.createElement('div');

// Bad
window.clearTimeout(1);

// Bad
document.createElement('div');