TypeScript Types

Complete TypeScript types documentation for Matrix UI components, props, and utility functions.

Type Safety

Matrix UI is built with TypeScript-first design. All components export their prop types for excellent development experience and compile-time safety.

UI Components

Basic UI component prop types

ButtonProps

import type { ButtonProps } from '@matrix-ui/components'

interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'
  size?: 'default' | 'sm' | 'lg' | 'icon'
  asChild?: boolean
}

// Usage
const MyButton: React.FC<ButtonProps> = ({ variant, size, ...props }) => {
  return <Button variant={variant} size={size} {...props} />
}

// With additional props
interface CustomButtonProps extends ButtonProps {
  loading?: boolean
  icon?: React.ReactNode
}

const CustomButton: React.FC<CustomButtonProps> = ({ 
  loading, 
  icon, 
  children, 
  disabled,
  ...buttonProps 
}) => {
  return (
    <Button disabled={disabled || loading} {...buttonProps}>
      {loading ? <Spinner /> : icon}
      {children}
    </Button>
  )
}

BadgeProps

import type { BadgeProps } from '@matrix-ui/components'
import type { VariantProps } from 'class-variance-authority'

interface BadgeProps 
  extends React.HTMLAttributes<HTMLDivElement>,
          VariantProps<typeof badgeVariants> {
  variant?: 'default' | 'secondary' | 'destructive' | 'outline'
}

// Usage with additional types
interface StatusBadgeProps extends BadgeProps {
  status: 'active' | 'inactive' | 'pending' | 'error'
}

const StatusBadge: React.FC<StatusBadgeProps> = ({ status, ...props }) => {
  const variantMap: Record<StatusBadgeProps['status'], BadgeProps['variant']> = {
    active: 'default',
    inactive: 'secondary', 
    pending: 'outline',
    error: 'destructive'
  }
  
  return <Badge variant={variantMap[status]} {...props} />
}

AvatarProps

import type { AvatarProps } from '@matrix-ui/components'

interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
  src?: string
  alt?: string
  fallback?: string
  size?: 'sm' | 'md' | 'lg' | 'xl'
}

// Extended avatar with status
interface UserAvatarProps extends AvatarProps {
  user: {
    name: string
    avatar?: string
    isOnline?: boolean
  }
  showStatus?: boolean
}

const UserAvatar: React.FC<UserAvatarProps> = ({ 
  user, 
  showStatus = false,
  ...avatarProps 
}) => {
  return (
    <div className="relative">
      <Avatar
        src={user.avatar}
        alt={user.name}
        fallback={user.name.charAt(0)}
        {...avatarProps}
      />
      {showStatus && (
        <div className={cn(
          'absolute bottom-0 right-0 h-3 w-3 rounded-full border-2 border-white',
          user.isOnline ? 'bg-green-500' : 'bg-gray-400'
        )} />
      )}
    </div>
  )
}

Layout Components

Layout and structural component types

Card Component Family

import type {
  CardProps,
  CardHeaderProps, 
  CardTitleProps,
  CardDescriptionProps,
  CardContentProps,
  CardFooterProps
} from '@matrix-ui/components'

interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
  children?: React.ReactNode
  asChild?: boolean
}

interface CardHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
  children?: React.ReactNode
}

interface CardTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
  children?: React.ReactNode
  asChild?: boolean
}

interface CardDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {
  children?: React.ReactNode
}

interface CardContentProps extends React.HTMLAttributes<HTMLDivElement> {
  children?: React.ReactNode
}

interface CardFooterProps extends React.HTMLAttributes<HTMLDivElement> {
  children?: React.ReactNode
}

// Usage example
interface ProductCardProps {
  product: {
    id: string
    name: string
    description: string
    price: number
    image: string
  }
  onAddToCart?: (productId: string) => void
}

const ProductCard: React.FC<ProductCardProps> = ({ product, onAddToCart }) => {
  return (
    <Card>
      <CardHeader>
        <CardTitle>{product.name}</CardTitle>
        <CardDescription>{product.description}</CardDescription>
      </CardHeader>
      <CardContent>
        <img src={product.image} alt={product.name} />
        <div className="text-2xl font-bold">${product.price}</div>
      </CardContent>
      <CardFooter>
        <Button onClick={() => onAddToCart?.(product.id)}>
          Add to Cart
        </Button>
      </CardFooter>
    </Card>
  )
}

Form Components

Form input and validation types

InputProps

import type { InputProps } from '@matrix-ui/components'

interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
  error?: boolean
  helperText?: string
}

// Extended form field
interface FormFieldProps extends InputProps {
  label?: string
  required?: boolean
  validation?: {
    required?: boolean
    minLength?: number
    maxLength?: number
    pattern?: RegExp
    custom?: (value: string) => string | undefined
  }
}

const FormField: React.FC<FormFieldProps> = ({ 
  label,
  required,
  validation,
  error,
  helperText,
  ...inputProps 
}) => {
  return (
    <div className="space-y-2">
      {label && (
        <label className="text-sm font-medium">
          {label} {required && <span className="text-red-500">*</span>}
        </label>
      )}
      <Input error={error} {...inputProps} />
      {helperText && (
        <p className={cn(
          'text-xs',
          error ? 'text-red-500' : 'text-muted-foreground'
        )}>
          {helperText}
        </p>
      )}
    </div>
  )
}

CheckboxProps & SwitchProps

import type { CheckboxProps, SwitchProps } from '@matrix-ui/components'

interface CheckboxProps extends React.InputHTMLAttributes<HTMLInputElement> {
  checked?: boolean
  onCheckedChange?: (checked: boolean) => void
  indeterminate?: boolean
}

interface SwitchProps extends React.InputHTMLAttributes<HTMLInputElement> {
  checked?: boolean
  onCheckedChange?: (checked: boolean) => void
}

// Settings component example
interface SettingsProps {
  settings: {
    notifications: boolean
    darkMode: boolean
    emailUpdates: boolean
  }
  onChange: (key: keyof SettingsProps['settings'], value: boolean) => void
}

const Settings: React.FC<SettingsProps> = ({ settings, onChange }) => {
  return (
    <div className="space-y-4">
      <div className="flex items-center justify-between">
        <label>Notifications</label>
        <Switch
          checked={settings.notifications}
          onCheckedChange={(checked) => onChange('notifications', checked)}
        />
      </div>
      
      <div className="flex items-center space-x-2">
        <Checkbox
          checked={settings.emailUpdates}
          onCheckedChange={(checked) => onChange('emailUpdates', checked)}
        />
        <label>Email Updates</label>
      </div>
    </div>
  )
}

Feedback Components

Loading, alert, and status component types

Alert Component Family

import type { AlertProps } from '@matrix-ui/components'
import type { VariantProps } from 'class-variance-authority'

interface AlertProps 
  extends React.HTMLAttributes<HTMLDivElement>,
          VariantProps<typeof alertVariants> {
  variant?: 'default' | 'destructive'
}

// Notification system types
type NotificationLevel = 'info' | 'success' | 'warning' | 'error'

interface NotificationProps extends Omit<AlertProps, 'variant'> {
  level: NotificationLevel
  title?: string
  message: string
  dismissible?: boolean
  onDismiss?: () => void
  autoHide?: boolean
  duration?: number
}

const Notification: React.FC<NotificationProps> = ({
  level,
  title,
  message,
  dismissible = true,
  onDismiss,
  autoHide = false,
  duration = 5000,
  ...props
}) => {
  const variantMap: Record<NotificationLevel, AlertProps['variant']> = {
    info: 'default',
    success: 'default',
    warning: 'default',
    error: 'destructive'
  }

  useEffect(() => {
    if (autoHide && onDismiss) {
      const timer = setTimeout(onDismiss, duration)
      return () => clearTimeout(timer)
    }
  }, [autoHide, duration, onDismiss])

  return (
    <Alert variant={variantMap[level]} {...props}>
      <div className="flex items-start justify-between">
        <div>
          {title && <AlertTitle>{title}</AlertTitle>}
          <AlertDescription>{message}</AlertDescription>
        </div>
        {dismissible && (
          <button onClick={onDismiss}>
            <X className="h-4 w-4" />
          </button>
        )}
      </div>
    </Alert>
  )
}

Type-Safe Development Tips

Strict TypeScript Config

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "noImplicitReturns": true,
    "noImplicitThis": true,
    "exactOptionalPropertyTypes": true
  }
}

Import/Export Patterns

// Export component and types together
export { Button } from './button'
export type { ButtonProps } from './button'

// Or use namespace exports
export * as Button from './button'

// Re-export types from index
export type {
  // Component props
  ButtonProps,
  CardProps,
  InputProps,
  
  // Utility types  
  Variant,
  Size,
  Status
} from './components'

Type Safety Best Practices

✓ Always define prop types for components

✓ Use generic types for reusable components

✓ Leverage discriminated unions for state management

✓ Use type guards for runtime type checking

✓ Export types alongside components

✓ Use readonly for immutable data