Valk UI

Modern UI component library for React with TypeScript

Documentation • Installation • Components • CLI

✨ Features

• 🎨 Modern Design: Beautiful and consistent components with Tailwind CSS
• ⚛️ React 18 & 19: Support for React 18 and React 19
• 📘 TypeScript: Fully typed and production-ready
• 🌙 Dark Mode: Native dark mode support
• 📦 Interactive CLI: Install only the components you need
• 🎯 Zero Heavy Dependencies: Lightweight and performant components
• ♿ Accessible: Built with accessibility in mind
• 🔧 Customizable: Easy to customize and extend

🚀 Installation

Install the package

npm install ui-valk
# or
pnpm add ui-valk
# or
yarn add ui-valk

Install peer dependencies

npm install react react-dom @heroicons/react @headlessui/react

For chart components (optional):

npm install chart.js react-chartjs-2

📦 Using the CLI

Valk UI includes an interactive CLI to install components directly into your project:

npx ui-valk

The CLI allows you to:

• ✅ Choose language (PT, EN, ES)
• ✅ Install by category or individually
• ✅ Set custom installation directory
• ✅ Automatic Tailwind CSS configuration

🎨 Available Components

📝 Forms (forms/)

• Button - Buttons with multiple variants (primary, secondary, outline, ghost, destructive) and sizes
• Input - Input fields with icon support, labels, and validation
• Select - Custom selector with search and multiple mode
• Checkbox - Custom checkbox with label and description
• Toggle - Switch toggle with different sizes
• DatePicker - Date selector with interactive calendar

💬 Feedback (feedback/)

• Modal - Responsive modal with different sizes
• Dialog - Accessible dialog with overlay
• Toast - Toast notification system
• ToastContext - Context provider for toasts
• StatusBadge - Badges to indicate status
• Badge - Generic customizable badge
• ProgressBar - Progress bar with different colors
• DropdownMenu - Accessible dropdown menu
• Command - Command palette (command search)
• ThemeToggle - Toggle to switch light/dark theme

📐 Layout (layout/)

• Card - Card with header, content and footer
• Avatar - Avatar with fallback to initials
• MetricCard - Card to display metrics and KPIs
• PaginatedTable - Paginated table with search and sorting
• Navigation - Navigation component
• Sidebar - Collapsible sidebar
• Tabs - Tab system
• Accordion - Expandable accordion
• Separator - Visual separator
• Sheet - Side panel (drawer)
• DocsSidebar - Sidebar for documentation

📊 Charts (charts/)

• BarChart - Comparative bar chart
• DonutChart - Donut chart
• LineChart - Temporal line chart

🎯 Basic Usage

Import components

import { Button, Input, Modal, Card } from 'ui-valk'

Complete example

import { Button, Input, Modal, Card, CardHeader, CardTitle, CardContent } from 'ui-valk'

function App() {
  const [isOpen, setIsOpen] = useState(false)

  return (
    <div className="p-8">
      <Card>
        <CardHeader>
          <CardTitle>Welcome to Valk UI</CardTitle>
        </CardHeader>
        <CardContent>
          <Input 
            label="Email" 
            placeholder="[email protected]" 
            type="email"
          />
          <Button 
            variant="primary" 
            size="lg"
            onClick={() => setIsOpen(true)}
          >
            Open Modal
          </Button>
        </CardContent>
      </Card>

      <Modal 
        isOpen={isOpen} 
        onClose={() => setIsOpen(false)} 
        title="Modal Title"
      >
        <p>Modal content here</p>
      </Modal>
    </div>
  )
}

🛠️ Requirements

• React: ^18.0.0 || ^19.0.0
• React DOM: ^18.0.0 || ^19.0.0
• TypeScript: ^5.0.0 (recommended)
• Tailwind CSS: ^3.0.0
• Node.js: ^18.0.0

Peer Dependencies

• @heroicons/react: ^2.0.0 (for icons)
• @headlessui/react: ^2.0.0 (for accessible components)
• react-router-dom: ^7.0.0 (optional, for navigation)

Optional Dependencies

• chart.js: ^4.0.0 and react-chartjs-2: ^5.0.0 (for chart components)

⚙️ Tailwind CSS Configuration

Valk UI requires Tailwind CSS. Add to your tailwind.config.js:

module.exports = {
  content: [
    "./src/**/*.{js,ts,jsx,tsx}",
    "./node_modules/ui-valk/dist/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {
      // Your customizations
    },
  },
  plugins: [],
}

And import the CSS in your main file:

@tailwind base;
@tailwind components;
@tailwind utilities;

📖 Complete Documentation

For complete documentation with examples, visit:

• Online Documentation (coming soon)
• GitHub Repository

🤝 Contributing

Contributions are welcome! Please:

1. Fork the project
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Tailwind CSS - Utility-first CSS framework
• Heroicons - SVG icons
• Chart.js - Chart library
• Headless UI - Accessible components

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

Made with ❤️ by Fernando Forastieri

⭐ If this project was useful to you, consider giving it a star!