@mks2508/basecoat-astro-components

Complete collection of 25 UI components and 12 icons for Astro projects, built with Basecoat CSS and enhanced with TypeScript support.

🚀 Features

• ✅ 25 Production-Ready Components organized by category
• ✅ 12 Cohesive Icons for consistent UI design
• ✅ Full TypeScript Support with proper Astro component typing
• ✅ Basecoat CSS Integration with custom enhancements
• ✅ Responsive Design with Tailwind v4 compatibility
• ✅ Accessibility First following ARIA guidelines
• ✅ Zero Configuration - just install and use

📦 Installation

npm install @mks2508/basecoat-astro-components

Prerequisites

Make sure you have these dependencies in your Astro project:

npm install astro basecoat-css tailwindcss @tailwindcss/vite

CSS Setup

You need to import Basecoat CSS and configure Tailwind in your project:

Option 1: Use the provided CSS file

Copy the example CSS file to your project:

---
// In your Layout.astro or main CSS file
import '@mks2508/basecoat-astro-components/styles/basecoat.css';
---

Option 2: Manual CSS setup

Create a CSS file (e.g., src/styles/global.css) with:

@import "tailwindcss";
@import "basecoat-css";

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ... other theme variables */
}

@layer base {
  * {
    @apply border-border outline-ring/50;
  }
  
  body {
    @apply bg-background text-foreground;
  }
}

JavaScript Setup (Required for Interactive Components)

Some components require Basecoat's JavaScript. Add this to your layout:

<!-- In your Layout.astro head section -->
<script is:inline src="https://cdn.jsdelivr.net/npm/[email protected]/dist/js/all.min.js" defer></script>

<!-- For Toast notifications, add this container to your body -->
<div id="toaster" class="toaster" data-align="end"></div>

Astro Configuration

Configure Tailwind in your astro.config.mjs:

import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: {
    plugins: [tailwindcss()]
  }
});

Interactive Components Requiring JavaScript

These components need the Basecoat JavaScript to function:

• Dropdown Menu - Menu interactions and keyboard navigation
• Popover - Show/hide and positioning
• Select - Dropdown functionality
• Sidebar - Toggle and responsive behavior
• Tabs - Tab switching and keyboard navigation
• Toast - Auto-dismiss and animations

🎯 Usage

Import Components

---
// Individual imports
import { Button, Card, Alert } from '@mks2508/basecoat-astro-components';
import { SunIcon, MoonIcon } from '@mks2508/basecoat-astro-components';

// Or use direct paths
import Button from '@mks2508/basecoat-astro-components/components/Button.astro';
import SunIcon from '@mks2508/basecoat-astro-components/icons/SunIcon.astro';
---

<Card title="Welcome">
  <p>Hello from Basecoat components!</p>
  <Button variant="primary">
    <SunIcon />
    Click me
  </Button>
</Card>

🧩 Components

Form Controls (9 components)

• Button - Customizable button with variants and sizes
• Input - Text input with validation support
• Label - Accessible form labels
• Select - Dropdown select with options
• Textarea - Multi-line text input with auto-resize
• Checkbox - Checkbox with custom styling
• Switch - Toggle switch component
• RadioGroup - Radio button groups
• Toggle - Toggle button component

Display (8 components)

• Card - Flexible card container with slots
• Alert - Alert messages with variants (success, warning, error)
• Badge - Status badges with color variants
• Avatar - User avatar with fallback text
• Progress - Progress bar with customizable values
• Skeleton - Loading skeleton placeholders
• Toast - Toast notifications with event system
• Breadcrumb - Navigation breadcrumb trails

Navigation (6 components)

• Tabs - Tabbed interface with accessibility
• SimpleTabs - Lightweight tab component
• Accordion - Collapsible content sections
• DropdownMenu - Dropdown menu with keyboard navigation
• Sidebar - Navigation sidebar with groups and submenus
• Table - Data table with styling

Overlays (4 components)

• AlertDialog - Modal alert dialogs
• Modal - General purpose modal dialogs
• Popover - Contextual popover content
• Tooltip - Hover tooltips with positioning

🎨 Icons (12 components)

• MonitorIcon - Display/monitor icon
• PlusIcon - Add/plus icon
• SettingsIcon - Settings/gear icon
• TrashIcon - Delete/trash icon
• BoltIcon - Lightning/performance icon
• SearchIcon - Search/magnifying glass icon
• PaletteIcon - Color/palette icon
• DownloadIcon - Download arrow icon
• ChevronDownIcon - Dropdown arrow icon
• MoonIcon - Dark mode icon
• CheckIcon - Checkmark/success icon
• SunIcon - Light mode icon

💡 Examples

Form with Validation

---
import { Card, Label, Input, Button, Alert } from '@mks2508/basecoat-astro-components';
---

<Card title="Contact Form">
  <form class="space-y-4">
    <div>
      <Label for="email">Email Address</Label>
      <Input id="email" type="email" placeholder="Enter your email" required />
    </div>
    
    <Alert variant="info" title="Info" description="All fields are required." />
    
    <Button variant="primary" type="submit">
      Submit Form
    </Button>
  </form>
</Card>

Navigation with Icons

---
import { Button, DropdownMenu } from '@mks2508/basecoat-astro-components';
import { SettingsIcon, SunIcon, MoonIcon } from '@mks2508/basecoat-astro-components';
---

<div class="flex items-center gap-2">
  <Button variant="outline">
    <SettingsIcon />
    Settings
  </Button>
  
  <Button variant="ghost" id="theme-toggle">
    <SunIcon id="light-icon" />
    <MoonIcon id="dark-icon" class="hidden" />
  </Button>
</div>

🎨 Styling

All components use Basecoat CSS classes and are fully compatible with Tailwind v4. You can customize styling by:

1. Override CSS Variables - Modify Basecoat's design tokens
2. Add Custom Classes - Use Tailwind utilities alongside component classes
3. Theme Integration - Works with any Basecoat-compatible theme

Example Customization

<Button variant="primary" class="!bg-purple-600 hover:!bg-purple-700">
  Custom Purple Button
</Button>

🔧 TypeScript Support

All components include full TypeScript definitions:

---
// TypeScript interfaces are automatically available
interface ButtonProps {
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'link' | 'destructive' | 'icon';
  size?: 'sm' | 'lg';
  disabled?: boolean;
  class?: string;
}
---

🤝 Contributing

Issues and pull requests welcome at GitHub repository.

📄 License

MIT License - see LICENSE file for details.

Built with ❤️ using Astro and Basecoat CSS