Story Card Component

A flexible and customizable story card component library with multiple layouts, themes, and interactive features. Built with React and vanilla JavaScript support.

Features

• 🎨 Multiple Layouts: Vertical, Horizontal, Grid, Masonry, Carousel, and Flip cards
• 🌈 5 Beautiful Themes: Default, Dark, Minimal, Elegant, and Modern
• 📱 Fully Responsive: Works perfectly on all device sizes
• ⚡ Performance Optimized: Lazy loading, smooth animations, and efficient rendering
• 🎯 Accessible: ARIA labels, keyboard navigation, and screen reader support
• 🔧 Highly Customizable: Extensive props and CSS custom properties
• 🚀 Vanilla JS Support: Can be used without React
• 📦 Zero Dependencies: Lightweight and fast

Installation

npm install story-card-component

Quick Start

React Usage

import React from 'react';
import { StoryCard, GridCard, CarouselCard } from 'story-card-component';

function App() {
  const story = {
    title: "Amazing Adventure",
    description: "An incredible journey through unknown lands...",
    image: "https://example.com/image.jpg",
    author: "John Doe",
    date: "2024-01-15",
    tags: ["Adventure", "Travel"]
  };

  return (
    <div>
      {/* Single Story Card */}
      <StoryCard {...story} />
      
      {/* Grid Layout */}
      <GridCard 
        stories={[story, story, story]} 
        columns={3} 
        theme="modern" 
      />
      
      {/* Carousel Layout */}
      <CarouselCard 
        stories={[story, story, story]} 
        autoPlay={true} 
        theme="elegant" 
      />
    </div>
  );
}

Vanilla JavaScript Usage

import { createStoryCard, StoryCardManager } from 'story-card-component';

// Create a single card
const card = createStoryCard({
  title: "Amazing Adventure",
  description: "An incredible journey through unknown lands...",
  image: "https://example.com/image.jpg",
  author: "John Doe",
  date: "2024-01-15",
  tags: ["Adventure", "Travel"],
  theme: "modern",
  onClick: (e, data) => console.log('Card clicked:', data)
});

document.body.appendChild(card);

// Create a managed grid
const manager = new StoryCardManager('#container', {
  stories: [story1, story2, story3],
  columns: 3,
  theme: 'modern',
  onCardClick: (story) => console.log('Story clicked:', story)
});

Layouts

1. Vertical Card (Default)

<StoryCard 
  title="Story Title"
  description="Story description..."
  image="image-url.jpg"
  layout="vertical"
  theme="default"
/>

2. Horizontal Card

<HorizontalCard 
  title="Story Title"
  description="Story description..."
  image="image-url.jpg"
  imagePosition="left" // or "right"
  theme="elegant"
/>

3. Grid Layout

<GridCard 
  stories={storiesArray}
  columns={3} // 1-6 columns
  gap="medium" // "small", "medium", "large"
  theme="modern"
  responsive={true}
  onCardClick={(e, data, index) => console.log('Card clicked:', index)}
/>

4. Masonry Layout

<MasonryCard 
  stories={storiesArray}
  columns={3} // 2-5 columns
  gap="medium"
  theme="minimal"
  onCardClick={(e, data, index) => console.log('Card clicked:', index)}
/>

5. Carousel Layout

<CarouselCard 
  stories={storiesArray}
  autoPlay={true}
  autoPlayInterval={3000}
  showArrows={true}
  showDots={true}
  theme="dark"
  onCardClick={(e, data, index) => console.log('Card clicked:', index)}
/>

6. Flip Card

<FlipCard 
  frontContent={<StoryCard {...frontStory} />}
  backContent={<StoryCard {...backStory} />}
  flipDirection="horizontal" // or "vertical"
  autoFlip={false}
  autoFlipInterval={5000}
  theme="elegant"
/>

Themes

Available Themes:

• default: Clean and modern design
• dark: Dark mode with light text
• minimal: Simple border design
• elegant: Gradient background with serif fonts
• modern: Bold typography with larger spacing

<StoryCard 
  title="Story Title"
  description="Story description..."
  theme="dark" // Choose your theme
/>

Props Reference

StoryCard Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | title | string | - | Card title | | description | string | - | Card description | | image | string | - | Image URL | | author | string | - | Author name | | date | string | - | Publication date | | tags | string[] | [] | Array of tags | | layout | string | 'vertical' | Layout type | | theme | string | 'default' | Theme type | | onClick | function | - | Click handler | | className | string | - | Additional CSS classes |

GridCard Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | stories | array | [] | Array of story objects | | columns | number | 3 | Number of columns (1-6) | | gap | string | 'medium' | Gap size between cards | | theme | string | 'default' | Theme for all cards | | responsive | boolean | true | Enable responsive behavior | | onCardClick | function | - | Click handler for cards |

CarouselCard Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | stories | array | [] | Array of story objects | | autoPlay | boolean | false | Enable auto-play | | autoPlayInterval | number | 3000 | Auto-play interval in ms | | showArrows | boolean | true | Show navigation arrows | | showDots | boolean | true | Show pagination dots | | theme | string | 'default' | Theme for all cards |

CSS Custom Properties

You can customize the appearance using CSS custom properties:

:root {
  /* Colors */
  --story-card-primary: #3b82f6;
  --story-card-secondary: #64748b;
  
  /* Typography */
  --story-card-font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  --story-card-font-size-base: 1rem;
  
  /* Spacing */
  --story-card-spacing-md: 1rem;
  --story-card-spacing-lg: 1.5rem;
  
  /* Border radius */
  --story-card-radius-lg: 0.75rem;
  
  /* Shadows */
  --story-card-shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
  
  /* Transitions */
  --story-card-transition-normal: 250ms ease-in-out;
}

Advanced Usage

StoryCardManager (Vanilla JS)

import { StoryCardManager } from 'story-card-component';

const manager = new StoryCardManager('#container', {
  stories: storiesArray,
  layout: 'grid',
  theme: 'modern',
  columns: 3,
  itemsPerPage: 12,
  sortBy: 'date',
  sortOrder: 'desc',
  onCardClick: (story) => console.log('Story clicked:', story)
});

// Filter by tags
manager.filterByTags(['Adventure', 'Travel']);

// Search stories
manager.search('amazing');

// Sort stories
manager.sortBy('title', 'asc');

// Navigate pages
manager.nextPage();
manager.previousPage();
manager.goToPage(3);

// Add new story
manager.addStory(newStory);

// Update story
manager.updateStory(0, updatedStory);

// Remove story
manager.removeStory(0);

// Get current state
const state = manager.getState();

Custom Styling

/* Custom card styles */
.story-card {
  border: 2px solid #e2e8f0;
  transition: all 0.3s ease;
}

.story-card:hover {
  border-color: #3b82f6;
  transform: translateY(-8px);
}

/* Custom theme */
.story-card--custom {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
}

.story-card--custom .story-card__title {
  color: white;
  text-shadow: 0 2px 4px rgba(0,0,0,0.3);
}

Browser Support

• Chrome 60+
• Firefox 55+
• Safari 12+
• Edge 79+

Contributing

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

License

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

Changelog

v1.0.0

• Initial release
• 6 different layouts
• 5 beautiful themes
• React and vanilla JS support
• Full responsive design
• Accessibility features
• Performance optimizations

Support

If you have any questions or need help, please open an issue on GitHub or contact us at [email protected].