API Reference

Note: This is a partial API reference showing the most commonly used props. For complete type definitions, see the TypeScript types exported from each component. All components extend standard HTML attributes where applicable.

Complete API documentation for all Nostromo UI components.

Tip: Import components from @jarllyng/nostromo or @jarllyng/nostromo to get full TypeScript support and autocomplete.

Core Components

Button


interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
  variant?: 'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link' | 'subtle'
  size?: 'default' | 'sm' | 'lg' | 'xl' | 'icon'
  state?: 'default' | 'loading' | 'success' | 'error'
  disabled?: boolean
  loading?: boolean
  loadingText?: string
  children: React.ReactNode
  className?: string
}

Input


interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> {
  variant?: 'default' | 'error' | 'success' | 'subtle'
  inputSize?: 'sm' | 'default' | 'lg'
  error?: boolean
  success?: boolean
  helperText?: string
  label?: string
  className?: string
  // ... all standard HTML input attributes
}

Dialog


interface DialogProps {
  open?: boolean
  onOpenChange?: (open: boolean) => void
  children: React.ReactNode
  className?: string
}
 
interface DialogContentProps {
  children: React.ReactNode
  className?: string
}
 
interface DialogHeaderProps {
  children: React.ReactNode
  className?: string
}
 
interface DialogTitleProps {
  children: React.ReactNode
  className?: string
}
 
interface DialogDescriptionProps {
  children: React.ReactNode
  className?: string
}

Card


interface CardProps {
  children: React.ReactNode
  className?: string
}
 
interface CardHeaderProps {
  children: React.ReactNode
  className?: string
}
 
interface CardTitleProps {
  children: React.ReactNode
  className?: string
}
 
interface CardDescriptionProps {
  children: React.ReactNode
  className?: string
}
 
interface CardContentProps {
  children: React.ReactNode
  className?: string
}
 
interface CardFooterProps {
  children: React.ReactNode
  className?: string
}

Badge


interface BadgeProps {
  variant?: 'default' | 'secondary' | 'destructive' | 'outline'
  size?: 'default' | 'sm' | 'lg'
  children: React.ReactNode
  className?: string
}

Alert


interface AlertProps {
  variant?: 'default' | 'destructive'
  children: React.ReactNode
  className?: string
}
 
interface AlertTitleProps {
  children: React.ReactNode
  className?: string
}
 
interface AlertDescriptionProps {
  children: React.ReactNode
  className?: string
}

Avatar


interface AvatarProps {
  src?: string
  alt?: string
  fallback?: string
  size?: 'sm' | 'md' | 'lg'
  className?: string
}

Checkbox


interface CheckboxProps {
  checked?: boolean
  onCheckedChange?: (checked: boolean) => void
  disabled?: boolean
  required?: boolean
  id?: string
  name?: string
  value?: string
  className?: string
}

Icon


interface IconProps {
  name: IconName  // See iconNames export for available icons (~170 icons)
  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl'
  weight?: 'thin' | 'light' | 'regular' | 'bold' | 'fill' | 'duotone'
  color?: 'current' | 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'muted'
  className?: string
  // ... all standard SVG attributes
}
 
// Note: For icons not in iconMap, import directly from 'phosphor-react'
// Example: import { CustomIcon } from 'phosphor-react'

Label


interface LabelProps {
  htmlFor?: string
  children: React.ReactNode
  className?: string
}

Pagination


interface PaginationProps {
  currentPage: number
  totalPages: number
  onPageChange: (page: number) => void
  showFirstLast?: boolean
  showPrevNext?: boolean
  className?: string
}

Progress


interface ProgressProps {
  value?: number
  max?: number
  className?: string
}

Select


interface SelectProps {
  value?: string
  onValueChange?: (value: string) => void
  disabled?: boolean
  children: React.ReactNode
  className?: string
}
 
interface SelectTriggerProps {
  children: React.ReactNode
  className?: string
}
 
interface SelectValueProps {
  placeholder?: string
  className?: string
}
 
interface SelectContentProps {
  children: React.ReactNode
  className?: string
}
 
interface SelectItemProps {
  value: string
  children: React.ReactNode
  className?: string
}

Separator


interface SeparatorProps {
  orientation?: 'horizontal' | 'vertical'
  className?: string
}

Skeleton


interface SkeletonProps {
  className?: string
}

Switch


interface SwitchProps {
  checked?: boolean
  onCheckedChange?: (checked: boolean) => void
  disabled?: boolean
  required?: boolean
  id?: string
  name?: string
  value?: string
  className?: string
}

Table


interface TableProps {
  children: React.ReactNode
  className?: string
}
 
interface TableHeaderProps {
  children: React.ReactNode
  className?: string
}
 
interface TableBodyProps {
  children: React.ReactNode
  className?: string
}
 
interface TableRowProps {
  children: React.ReactNode
  className?: string
}
 
interface TableHeadProps {
  children: React.ReactNode
  className?: string
}
 
interface TableCellProps {
  children: React.ReactNode
  className?: string
}

DataTable


interface DataTableProps<T = Record<string, unknown>> {
  data: T[]
  columns: TableColumn<T>[]
  searchable?: boolean
  filterable?: boolean
  filters?: ColumnFilter<T>[]
  showPagination?: boolean
  defaultPageSize?: number
  onSearch?: (searchTerm: string, filteredData: T[]) => void
  onFilter?: (filters: Record<string, unknown>, filteredData: T[]) => void
  className?: string
}
 
interface ColumnFilter<T = Record<string, unknown>> {
  key: string
  type: 'text' | 'select' | 'number' | 'date' | 'boolean'
  options?: Array<{ label: string; value: string | number }>
  placeholder?: string
  filterFn?: (value: unknown, record: T) => boolean
}

Calendar


interface CalendarProps {
  mode?: 'single' | 'range' | 'multiple'
  value?: Date | Date[] | { from?: Date; to?: Date }
  defaultValue?: Date | Date[] | { from?: Date; to?: Date }
  onChange?: (value: Date | Date[] | { from?: Date; to?: Date } | undefined) => void
  minDate?: Date
  maxDate?: Date
  disabledDates?: Date[]
  disabledDays?: number[]
  locale?: string
  placeholder?: string
  label?: string
  error?: boolean
  helperText?: string
  className?: string
}

Charts


interface ChartProps {
  type: 'line' | 'bar' | 'pie' | 'area'
  data: ChartDataPoint[]
  dataKeys: string[]
  xAxisKey?: string
  colors?: (string | undefined)[]
  showGrid?: boolean
  showLegend?: boolean
  showTooltip?: boolean
  title?: string
  description?: string
  className?: string
  height?: number
  ariaLabel?: string
  ariaLabelledBy?: string
  strokeWidth?: number
  fillOpacity?: number
}
 
interface ChartDataPoint {
  name: string
  [key: string]: string | number
}

Tabs


interface TabsProps {
  defaultValue?: string
  value?: string
  onValueChange?: (value: string) => void
  children: React.ReactNode
  className?: string
}
 
interface TabsListProps {
  children: React.ReactNode
  className?: string
}
 
interface TabsTriggerProps {
  value: string
  children: React.ReactNode
  className?: string
}
 
interface TabsContentProps {
  value: string
  children: React.ReactNode
  className?: string
}

Textarea


interface TextareaProps {
  placeholder?: string
  disabled?: boolean
  value?: string
  onChange?: (event: React.ChangeEvent<HTMLTextAreaElement>) => void
  className?: string
  id?: string
  name?: string
  required?: boolean
  rows?: number
}

Toast


interface ToastProps {
  title?: string
  description?: string
  variant?: 'default' | 'destructive'
  action?: React.ReactNode
  children?: React.ReactNode
  className?: string
}


interface TooltipProps {
  children: React.ReactNode
  content: React.ReactNode
  side?: 'top' | 'right' | 'bottom' | 'left'
  align?: 'start' | 'center' | 'end'
  className?: string
}

Marketing Components

Hero


interface HeroProps {
  title: string
  subtitle?: string
  cta?: React.ReactNode
  size?: 'sm' | 'md' | 'lg' | 'xl'
  variant?: 'default' | 'muted' | 'accent'
  contentAlign?: 'left' | 'center' | 'right'
  titleSize?: 'sm' | 'md' | 'lg' | 'xl'
  subtitleSize?: 'sm' | 'md' | 'lg'
  backgroundImage?: string
  overlay?: boolean
  className?: string
}

Features


interface FeaturesProps {
  features: Array<{
    id: string
    title: string
    description: string
    icon?: React.ReactNode
    iconVariant?: 'default' | 'accent' | 'muted' | 'success' | 'warning' | 'error'
  }>
  title?: string
  subtitle?: string
  columns?: 1 | 2 | 3 | 4
  variant?: 'default' | 'muted' | 'accent'
  cardVariant?: 'default' | 'accent' | 'muted'
  centered?: boolean
  className?: string
}

Gallery


interface GalleryProps {
  images: Array<{
    src: string
    alt: string
    title?: string
    description?: string
  }>
  className?: string
}

LogoWall


interface LogoWallProps {
  logos: Array<{
    src: string
    alt: string
    href?: string
  }>
  className?: string
}

Pricing


interface PricingProps {
  plans: Array<{
    id: string
    name: string
    description?: string
    price: {
      monthly: number
      yearly?: number
    }
    currency?: string
    period?: string
    features: Array<{
      id: string
      name: string
      included: boolean
    }>
    cta: {
      text: string
      href?: string
      onClick?: () => void
    }
    badge?: {
      text: string
      variant?: 'default' | 'accent' | 'success' | 'warning'
    }
    popular?: boolean
  }>
  title?: string
  subtitle?: string
  columns?: 1 | 2 | 3 | 4
  variant?: 'default' | 'muted' | 'accent'
  showYearly?: boolean
  onToggleBilling?: (yearly: boolean) => void
  className?: string
}

Testimonials


interface TestimonialsProps {
  testimonials: Array<{
    id: string
    name: string
    role: string
    company?: string
    content: string
    avatar?: string
    rating?: number
  }>
  title?: string
  subtitle?: string
  columns?: 1 | 2 | 3 | 4
  variant?: 'default' | 'muted' | 'accent'
  cardVariant?: 'default' | 'accent' | 'muted'
  showRatings?: boolean
  className?: string
}

TypeScript Support

All components are fully typed with TypeScript. Import types directly:


import type { ButtonProps, InputProps } from '@jarllyng/nostromo'

Common Patterns

Form Integration


import { useForm } from 'react-hook-form'
import { Button, Input, Label } from '@jarllyng/nostromo'
 
function ContactForm() {
  const { register, handleSubmit } = useForm()
  
  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <Label htmlFor="email">Email</Label>
      <Input {...register('email')} id="email" type="email" />
      <Button type="submit">Submit</Button>
    </form>
  )
}

State Management


import { useState } from 'react'
import { Dialog, DialogContent, DialogTrigger } from '@jarllyng/nostromo'
 
function MyDialog() {
  const [open, setOpen] = useState(false)
  
  return (
    <Dialog open={open} onOpenChange={setOpen}>
      <DialogTrigger>Open</DialogTrigger>
      <DialogContent>
        <p>Dialog content</p>
      </DialogContent>
    </Dialog>
  )
}

Accessibility

All components follow WCAG 2.1 AA guidelines:

Keyboard Navigation - Full keyboard support
Screen Readers - Proper ARIA attributes
Focus Management - Visible focus indicators
Color Contrast - Meets accessibility standards

Performance

Tree Shaking - Import only what you need
Bundle Size - Optimized for minimal impact
SSR Compatible - Works with Next.js, Remix, etc.
No Runtime Dependencies - Zero runtime overhead