wishborn/fancy-flux

Custom Flux UI components - carousel, color-picker, and emoji-select

54 3

laravel components carousel ui livewire flux color-picker emoji-select

Install
`composer require wishborn/fancy-flux`
Latest Version:	1.0.17
PHP:	^8.2

Maintainer: wishborn

Fancy Flux

Custom Flux UI components for Laravel Livewire applications.

Fancy Flux Components

Components

⚡ Action

A reusable button component with standalone colors, behavioral states, shape variants, avatars, badges, icons, emojis, and flexible placement.

Quick Example:

<flux:action icon="pencil">Edit</flux:action>
<flux:action color="blue" emoji="fire">Hot!</flux:action>
<flux:action color="red" badge="3">Alerts</flux:action>
<flux:action variant="circle" icon="play" />
<flux:action avatar="/img/user.jpg" badge="Admin">John</flux:action>

📖 Full Documentation | 💡 Examples

🎠 Carousel

A flexible carousel/slideshow component with multiple variants:

Directional - Navigation with prev/next arrows, supports autoplay
Wizard - Step-based navigation with numbered indicators, perfect for multi-step forms
Thumbnail - Image-based navigation with preview thumbnails

Quick Example:

<flux:carousel :data="$slides" autoplay />

📖 Full Documentation | 💡 Examples

🎨 Color Picker

A native color input component with enhanced UI, swatch preview, and preset support.

Quick Example:

<flux:color-picker label="Primary Color" wire:model="primaryColor" />

📖 Full Documentation | 💡 Examples

😀 Emoji

Display emojis using slugs, classic emoticons, or raw characters - like flux:icon but for emoji.

Quick Example:

<flux:emoji name="fire" />           {{-- 🔥 from slug --}}
<flux:emoji name=":)" />             {{-- 😊 from emoticon --}}
<flux:emoji name="rocket" size="lg" />

📖 Full Documentation

🎯 Emoji Select

A composable emoji picker component with category navigation, search, and customizable styling.

Quick Example:

<flux:emoji-select wire:model.live="selectedEmoji" />

📖 Full Documentation | 💡 Examples

📅 Timeline

Interactive narrative timelines powered by TimelineJS3. Supports eras, groups, media, lazy loading in carousels, and dark mode.

Quick Example:

<flux:timeline :data="$timeline" height="500px" />

{{-- Shorthand with just events --}}
<flux:timeline :events="$events" />

{{-- Named with custom controls --}}
<flux:timeline name="history" :data="$timeline">
    <div class="flex gap-2 p-2">
        <flux:button size="xs" icon="chevron-left" x-on:click="Flux.timeline('history').goToPrev()" />
        <flux:button size="xs" icon="chevron-right" x-on:click="Flux.timeline('history').goToNext()" />
    </div>
</flux:timeline>

📖 Full Documentation | 💡 Examples

📈 D3 Visualizations (Moved to Fancy Pro)

Note: D3 visualizations have been moved to the wishborn/fancy-pro package for better separation of premium features.

composer require wishborn/fancy-pro

📊 Fancy Table

Advanced data table with composable architecture, expandable row trays, and Carousel-powered pagination.

Note: Named <flux:fancy-table> to avoid conflicts with official Flux Pro table component.

Quick Example:

{{-- Data-driven mode --}}
<flux:fancy-table :columns="$columns" :rows="$rows" />

{{-- Composable mode --}}
<flux:fancy-table>
    <flux:fancy-table.columns>
        <flux:fancy-table.column name="name" label="Name" sortable />
        <flux:fancy-table.column name="email" label="Email" />
    </flux:fancy-table.columns>
    <flux:fancy-table.body :rows="$users">
        <flux:fancy-table.row :row="$row">
            <flux:fancy-table.cell>{{ $row->name }}</flux:fancy-table.cell>
            <flux:fancy-table.cell>{{ $row->email }}</flux:fancy-table.cell>
        </flux:fancy-table.row>
    </flux:fancy-table.body>
</flux:fancy-table>

Features:

Data-driven and composable slot-based modes
Sortable, resizable, and reorderable columns
Expandable row trays with nested content support
Multi-select with wire:model binding
Search with deep path query support
Carousel-powered pagination

📖 Full Documentation

FANCY Facade

The FANCY facade provides programmatic access to FancyFlux features:

// Emoji lookup (787+ emojis with slug-based access)
FANCY::emoji('fire');           // Returns: 🔥
FANCY::emoji(':)');             // Returns: 😊 (emoticon support!)
FANCY::emoji()->list();         // Get all emoji slugs
FANCY::emoji()->search('heart'); // Search emojis
FANCY::emoji()->emoticons();    // Get all supported emoticons

// Carousel control
FANCY::carousel('wizard')->next();
FANCY::carousel('wizard')->goTo('step-3');

// Timeline control
FANCY::timeline('my-timeline')->goToNext();
FANCY::timeline('my-timeline')->zoomIn();
FANCY::timeline('my-timeline')->add([...]);

// Table control
FANCY::table('users')->nextPage();
FANCY::table('users')->sortBy('name', 'asc');
FANCY::table('users')->toggleTray('row-1');

// Configuration
FANCY::prefix();            // Custom prefix or null
FANCY::components();        // List of components

📖 Full Documentation

Installation

composer require wishborn/fancy-flux

Component Prefix Configuration

To avoid naming conflicts with official Flux components or other custom components, you can configure a custom prefix for Fancy Flux components.

Publish the config file:

php artisan vendor:publish --tag=fancy-flux-config

Configure in config/fancy-flux.php:

return [
    'prefix' => 'fancy',
    'use_flux_namespace' => true,
    'enable_demo_routes' => false,
];

Configuration Priority:

Configuration is loaded in this order (later values override earlier ones):

Default PHP config (config/fancy-flux.php) - Base defaults
Environment variables (.env) - Highest priority, overrides PHP config

Environment Variables (Optional Override):

You can override PHP config with environment variables for environment-specific settings:

FANCY_FLUX_PREFIX=fancy
FANCY_FLUX_USE_FLUX_NAMESPACE=true
FANCY_FLUX_ENABLE_DEMO_ROUTES=false

Usage Examples:

No prefix (default): Components available as <flux:carousel>
With prefix 'fancy': Components available as <fancy:carousel> (and optionally <flux:carousel> if use_flux_namespace is true)

Configuration Options:

prefix - Custom prefix for components (e.g., "fancy", "custom", "myapp"). Set to null for no prefix.
use_flux_namespace - When true, components are also available in the flux namespace for backward compatibility. Set to false to use ONLY the prefixed namespace.
enable_demo_routes - When true, demo routes are loaded from the package at /fancy-flux-demos/*. Set to false to publish and customize routes yourself.

Why use a prefix?

Avoid conflicts: If Flux releases an official carousel component, your prefixed version won't conflict
Multiple packages: If you use multiple custom Flux component packages, prefixes prevent conflicts
Clear ownership: Makes it clear which components are from Fancy Flux vs official Flux

Documentation

Usage Guide - Comprehensive documentation for all components
Component Docs - Detailed guides for each component:
- Action
- Carousel
- Color Picker
- Emoji
- Emoji Select
- Timeline
- Fancy Table
- FANCY Facade
Prefix Configuration - Configure custom component prefixes to avoid naming conflicts
Troubleshooting - Common issues and solutions by version

Demos

Ready-to-use examples are available in the demos/ folder. Copy the demo files into your Laravel application to get started quickly:

Action Examples - State variants, icons, emojis, and placements
Basic Carousel - Simple data-driven carousel
Wizard Form - Multi-step form with validation
Nested Carousel - Nested carousels with parent advancement
Dynamic Carousel - Add/remove slides dynamically
Color Picker Examples - All color picker variants
Emoji Select Examples - All emoji select variants
Timeline Examples - Standalone, with controls, inside carousel

See the demos README for details.

Laravel Boost Integration

Fancy Flux includes AI guidelines for Laravel Boost. When you install this package and run php artisan boost:install, Boost will automatically load the guidelines to help AI assistants generate correct code for Fancy Flux components.

Custom AI Guidelines

You can also add custom AI guidelines for Fancy Flux by creating a .ai/guidelines/fancy-flux.md file in your application. This allows you to customize how AI assistants understand and use Fancy Flux components in your specific project context.

Upgrade Guide

General Upgrade Steps

Update via Composer:

# Update to latest version
composer update wishborn/fancy-flux

# Or update to a specific version
composer require wishborn/fancy-flux:^1.0.8

Clear caches:

php artisan config:clear
php artisan view:clear

Review changelog: Check CHANGELOG.md for version-specific changes
Test your application: Verify all components work as expected

Upgrading to 1.0.8+

New Feature: Component Prefix Configuration

Version 1.0.8 introduces optional component prefix configuration to avoid naming conflicts. This is backward compatible - existing code will continue to work without changes.

Optional: Configure a Prefix

If you want to use a custom prefix (recommended for new projects):

Publish the config file:

php artisan vendor:publish --tag=fancy-flux-config

Set prefix in config/fancy-flux.php:

return [
    'prefix' => 'fancy',
    'use_flux_namespace' => true,
    'enable_demo_routes' => false,
];

Clear config cache:
```
php artisan config:clear
```

No Action Required

If you don't configure a prefix, components continue to work exactly as before:

<flux:carousel> - Still works
<flux:color-picker> - Still works
<flux:emoji-select> - Still works

Migration Path (Optional)

If you want to migrate to a prefixed namespace:

Set FANCY_FLUX_PREFIX and keep FANCY_FLUX_USE_FLUX_NAMESPACE=true
Gradually update templates to use the prefixed version
Once all templates are updated, optionally set FANCY_FLUX_USE_FLUX_NAMESPACE=false

See Prefix Configuration for detailed migration steps.

Requirements

PHP 8.2+
Laravel 10+ / 11+ / 12+
Livewire 3.7+ / 4.0+
Flux UI 2.0+

License

MIT