Docs/Usage

Usage

Learn how to use ReacUI components effectively in your React projects

Basic Usage

After installing ReacUI, you can start importing and using components in your React application. All components are exported from the main package entry point.

import { Button, Card, Input } from 'reacui';

function MyComponent() {
  return (
    <div>
      <Card className="p-4">
        <h2 className="text-xl font-bold">Hello World</h2>
        <p className="mt-2">This is a simple card component with custom content.</p>
        <div className="mt-4">
          <Button variant="primary">Click Me</Button>
        </div>
      </Card>
    </div>
  );
}

Hello World

This is a simple card component with custom content.

Tip

All ReacUI components are built to be fully compatible with React Server Components in Next.js. For client-side interactivity, some components will need to be used within client components.

Component Props

ReacUI components accept standardized props for consistency. Most components share common props like className, disabled, and variant.

Button Component

Button Variants

Button Sizes

Button States

Input Component

Basic Inputs

Password is required

Input with Icon

Form Group

Each component's documentation page provides a complete list of available props. In general, ReacUI components are designed to feel familiar if you've used other React component libraries.

Styling Components

ReacUI is built with Tailwind CSS, making it easy to customize components using Tailwind classes. You can pass Tailwind classes via the className prop to override default styles.

// Default button
<Button variant="primary">Default Button</Button>

// Customized button with Tailwind classes
<Button 
  variant="primary"
  className="bg-gradient-to-r from-purple-500 to-pink-500 hover:from-purple-600 hover:to-pink-600 border-none shadow-lg"
>
  Customized Button
</Button>

Theme Customization

For global styling changes, you can customize your Tailwind config to match your brand colors. ReacUI will automatically use these colors:

// tailwind.config.js
module.exports = {
  theme: {
    extend: {
      colors: {
        primary: {
          50: '#f0f9ff',
          100: '#e0f2fe',
          /* ... */
          600: '#0284c7',  // Your primary brand color
          /* ... */
          900: '#0c4a6e',
        },
        secondary: {
          /* Your secondary colors */
        },
      },
    },
  },
}

Common Patterns

Here are some common patterns and component combinations that you'll find useful:

Layout Containers

<Card>
  <Card.Header>
    <Card.Title>Dashboard</Card.Title>
    <Card.Description>Your recent activity</Card.Description>
  </Card.Header>
  <Card.Content>
    {/* Card content */}
  </Card.Content>
  <Card.Footer>
    <Button variant="outline" size="sm">View All</Button>
  </Card.Footer>
</Card>

Data Display

<Table>
  <Table.Header>
    <Table.Row>
      <Table.Head>Name</Table.Head>
      <Table.Head>Email</Table.Head>
      <Table.Head>Status</Table.Head>
      <Table.Head>Actions</Table.Head>
    </Table.Row>
  </Table.Header>
  <Table.Body>
    {users.map(user => (
      <Table.Row key={user.id}>
        <Table.Cell>{user.name}</Table.Cell>
        <Table.Cell>{user.email}</Table.Cell>
        <Table.Cell>
          <Badge variant={user.status === 'active' ? 'success' : 'warning'}>
            {user.status}
          </Badge>
        </Table.Cell>
        <Table.Cell>
          <Button variant="ghost" size="sm">Edit</Button>
        </Table.Cell>
      </Table.Row>
    ))}
  </Table.Body>
</Table>

Notifications and Alerts

// Success Alert
<Alert variant="success">
  <Alert.Icon />
  <Alert.Title>Success!</Alert.Title>
  <Alert.Description>Your changes have been saved successfully.</Alert.Description>
</Alert>

// Error Alert
<Alert variant="error">
  <Alert.Icon />
  <Alert.Title>Error</Alert.Title>
  <Alert.Description>There was a problem with your submission.</Alert.Description>
</Alert>

Conditional Rendering

// Conditional rendering
function UserProfile({ user, isLoading }) {
  if (isLoading) {
    return <LoadingSpinner />;
  }
  
  if (!user) {
    return (
      <EmptyState
        message="No profile found"
        action={<Button>Sign In</Button>}
      />
    );
  }
  
  return (
    <ProfileCard
      name={user.name}
      avatar={user.avatar}
      stats={user.stats}
    />
  );
}

Conditional Rendering Preview

Loading State

isLoading === true

Empty State

No profile found

user === null

User Profile

JD

Jane Doe

jane@example.com

142
Posts
3.2k
Followers
256
Following
user provided

Working with Forms

ReacUI provides form components that work well together and are easy to integrate with form libraries like React Hook Form or Formik.

import { useState } from 'react';
import { Button, Card, Input, Checkbox, Select } from 'reacui';

function SignupForm() {
  const [formData, setFormData] = useState({
    name: '',
    email: '',
    password: '',
    role: '',
    agreeToTerms: false
  });
  
  const handleChange = (e) => {
    const { name, value, type, checked } = e.target;
    setFormData(prev => ({
      ...prev,
      [name]: type === 'checkbox' ? checked : value
    }));
  };
  
  const handleSubmit = (e) => {
    e.preventDefault();
    console.log('Form submitted:', formData);
    // Submit to your API
  };
  
  return (
    <Card className="p-6 max-w-md mx-auto">
      <h2 className="text-xl font-bold mb-4">Create Account</h2>
      
      <form onSubmit={handleSubmit}>
        <div className="space-y-4">
          <Input
            label="Full Name"
            name="name"
            value={formData.name}
            onChange={handleChange}
            required
          />
          
          <Input
            label="Email Address"
            name="email"
            type="email"
            value={formData.email}
            onChange={handleChange}
            required
          />
          
          <Input
            label="Password"
            name="password"
            type="password"
            value={formData.password}
            onChange={handleChange}
            required
          />
          
          <Select
            label="Role"
            name="role"
            value={formData.role}
            onChange={handleChange}
            required
          >
            <option value="">Select a role</option>
            <option value="developer">Developer</option>
            <option value="designer">Designer</option>
            <option value="manager">Manager</option>
          </Select>
          
          <Checkbox
            name="agreeToTerms"
            checked={formData.agreeToTerms}
            onChange={handleChange}
            label="I agree to the terms and conditions"
            required
          />
          
          <Button type="submit" variant="primary" className="w-full">
            Create Account
          </Button>
        </div>
      </form>
    </Card>
  );
}

React Hook Form Integration

ReacUI components work seamlessly with React Hook Form. Here's how to use them together:

import { useForm } from 'react-hook-form';
import { Button, Input, Checkbox } from 'reacui';

function LoginForm() {
  const { register, handleSubmit, formState: { errors } } = useForm();
  
  const onSubmit = (data) => {
    console.log('Form submitted:', data);
    // Submit to your API
  };
  
  return (
    <form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
      <Input
        label="Email"
        error={errors.email?.message}
        {...register('email', { 
          required: 'Email is required',
          pattern: {
            value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+.[A-Z]{2,}$/i,
            message: 'Invalid email address'
          }
        })}
      />
      
      <Input
        type="password"
        label="Password"
        error={errors.password?.message}
        {...register('password', { 
          required: 'Password is required',
          minLength: {
            value: 8,
            message: 'Password must be at least 8 characters'
          }
        })}
      />
      
      <Checkbox
        label="Remember me"
        {...register('remember')}
      />
      
      <Button type="submit" variant="primary">
        Sign In
      </Button>
    </form>
  );
}

Advanced Usage

Composition Patterns

ReacUI components are designed to be composable. You can combine them in various ways to create complex UIs:

// Component Composition
function Layout({ children }) {
  return (
    <div className="layout">
      {children}
    </div>
  );
}

function Sidebar({ children }) {
  return (
    <aside className="sidebar">
      {children}
    </aside>
  );
}

function Content({ children }) {
  return (
    <main className="content">
      {children}
    </main>
  );
}

function Dashboard() {
  return (
    <Layout>
      <Sidebar>
        <NavLinks />
        <ThemeToggle />
      </Sidebar>
      <Content>
        <Header />
        <DataGrid />
        <Footer />
      </Content>
    </Layout>
  );
}

Component Composition Preview

AppName

Dashboard Overview

Total Users

8,249

+14% from last month

Revenue

$23,432

+8% from last month

Conversion

3.6%

-2.3% from last month

Recent Users

NameEmailStatus
John Smithjohn@example.comActive
Alice Johnsonalice@example.comActive
Robert Brownrobert@example.comInactive
© 2023 Example App. All rights reserved.

Best Practices

Use Consistent Patterns

Maintain consistency in your UI by using the same component variants and sizes for similar actions throughout your application.

Follow Accessibility Guidelines

Always include proper labels, aria attributes, and ensure keyboard navigation works correctly. ReacUI handles most of this for you, but always test your implementation.

Create Component Compositions

Instead of building complex components from scratch, compose existing components together to create new UIs. This maintains consistency and reduces code duplication.

Optimize for Performance

For large lists or complex UIs, use virtualization, pagination, and other performance optimization techniques. Consider code-splitting to reduce initial bundle size.

Common Pitfalls to Avoid

  • Overriding Too Many Styles

    Instead of heavily customizing components with inline styles or className overrides, consider creating your own component wrappers or extending the theme.

  • Ignoring Mobile Responsiveness

    Always test your UI on different screen sizes and ensure it's fully responsive. Use responsive utilities provided by Tailwind for adaptable layouts.

  • Missing Feedback States

    Always provide appropriate feedback for user actions. Use loading states, success/error messages, and transitions to create a polished user experience.