@electroplix/components is now ready to use

Electroplix Logo
Electroplix

COMPONENTS

@electroplix/components

@electroplix/components is a library of 159 production-grade React components for Next.js 16. All components are theme-aware via a single ElectroplixProvider context, require only react and react-dom as peer dependencies, and ship as an ESM-only bundle fully compatible with React 19 and the App Router.

Installation & Setup

Requirements: Node.js ≥ 18, Next.js ^16.2.6, React 19.2.5.

npm install @electroplix/components react@19.2.5 react-dom@19.2.5
# or
pnpm add @electroplix/components react@19.2.5 react-dom@19.2.5

The library has no runtime dependencies — only react and react-dom are required as peers.

Next.js Configuration

Add transpilePackages to next.config.mjs. Without this, Next.js cannot process the ESM-only bundle and throws a module resolution error.

// next.config.mjs
const nextConfig = {
  transpilePackages: ['@electroplix/components'],
  reactStrictMode: true,
};
export default nextConfig;

Also set moduleResolution: "bundler" and target: "es2022" in your tsconfig.json for full TypeScript compatibility.

Provider Setup

All components require the ElectroplixProvider context. Because it is a Client Component ("use client"), wrap it in a dedicated client boundary file and keep your root layout a Server Component.

// src/app/ClientLayout.tsx
'use client';
import { ElectroplixProvider } from '@electroplix/components';
import type { ReactNode } from 'react';

export default function ClientLayout({ children }: { children: ReactNode }) {
  return (
    <ElectroplixProvider config={{ accentColor: '#8B5CF6' }}>
      {children}
    </ElectroplixProvider>
  );
}

// src/app/layout.tsx  (Server Component)
import ClientLayout from './ClientLayout';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ClientLayout>{children}</ClientLayout>
      </body>
    </html>
  );
}

  • Never put ElectroplixProvider directly in a Server Component. Always wrap it in a file that has 'use client' at the top.
  • Add the provider once in the root layout — all 159 components inherit the theme automatically.

Theme Configuration

Theme values cascade from defaults → global overrides → per-category overrides → individual component props:

  • defaultCategoryTheme (built-in)
  • Global BaseTheme overrides — bgColor, accentColor, radius, fontFamily, etc.
  • Per-category overrides — buttons.bgColor, navigation.sticky, forms.inputBg, etc.
  • Individual component prop overrides — passed directly at usage site

Inline config (simplest) — pass a config object directly to ElectroplixProvider:

import type { ElectroplixConfig } from '@electroplix/components';

const config: ElectroplixConfig = {
  // Global overrides
  bgColor: '#0b0b0c',
  accentColor: '#8B5CF6',
  fontFamily: 'Inter, sans-serif',
  radius: 8,
  // Per-category overrides
  buttons: { bgColor: '#7c3aed', radius: 6 },
  navigation: { sticky: true },
  blog: { tagBg: '#1e1b4b', tagColor: '#a5b4fc' },
};

<ElectroplixProvider config={config}>{children}</ElectroplixProvider>

File-based config (type-safe) — use defineConfig from the server-safe subpath for full TypeScript autocomplete:

// electroplix.config.ts
import { defineConfig } from '@electroplix/components/config';

export default defineConfig({
  bgColor: '#0b0b0c',
  accentColor: '#8B5CF6',
  navigation: { bgColor: '#111827', sticky: true },
  buttons: { bgColor: '#7c3aed', radius: 6, fontWeight: '600' },
  forms: { inputBg: '#1f2937', inputText: '#f9fafb' },
  hero: { bgColor: '#030712' },
});

// ClientLayout.tsx — import and pass the config file
import config from '../../electroplix.config';
<ElectroplixProvider config={config}>{children}</ElectroplixProvider>

Per-Category Hooks

Each of the 18 categories exposes a typed hook for reading the merged theme inside a Client Component. All hooks require a client context — they cannot be used in Server Components.

'use client';
import { useButtonTheme } from '@electroplix/components';

export function ThemedButton({ label }: { label: string }) {
  const theme = useButtonTheme();
  return (
    <button style={{
      background: theme.bgColor,
      color: theme.textColor,
      borderRadius: theme.radius,
      padding: `${theme.paddingY}px ${theme.paddingX}px`,
    }}>
      {label}
    </button>
  );
}

  • useNavTheme — Navigation
  • useHeroTheme — Hero
  • useButtonTheme — Buttons
  • useFormsTheme — Forms
  • useContentTheme — Content
  • useDataDisplayTheme — Data Display
  • useEcommerceTheme — Ecommerce
  • useListsCardsTheme — Lists & Cards
  • useMarketingTheme — Marketing
  • useMediaTheme — Media
  • useMiscTheme — Miscellaneous
  • useModalsTheme — Modals
  • useOnboardingTheme — Onboarding
  • useSearchTheme — Search
  • useSiteIdentityTheme — Site Identity
  • useSocialTheme — Social
  • useUserAccountsTheme — User Accounts
  • useBlogTheme — Blog

Icons

100+ inline SVG icons are bundled with zero additional dependencies. Use the Icon component with any name from ICON_NAMES.

import { Icon, ICON_NAMES } from '@electroplix/components';

// Render a specific icon
<Icon name="shield" size={24} color="#8B5CF6" />

// Discover all available names
console.log(ICON_NAMES);

Server-Safe Config Subpath

Use @electroplix/components/config in Server Components to access theme values without importing the React client bundle. Exports defaultConfig, defineConfig, and mergeTheme.

// Server Component — no "use client" needed
import { defaultConfig, defineConfig, mergeTheme } from '@electroplix/components/config';

const customConfig = defineConfig({ buttons: { bgColor: '#1d4ed8' } });
const mergedButtons = mergeTheme(defaultConfig.buttons, customConfig.buttons);

All 18 Component Categories

Every category page requires "use client" because components use React state internally. Below are minimal working examples for all 18 categories.

1. Navigation (11 components)

'use client';
import {
  PrimaryNav, MegaMenu, SidebarMenu, Tabs, Breadcrumbs,
  Pagination, Stepper, AnchorLinks, SideDrawerNav,
  LanguageSelector, Footer,
} from '@electroplix/components';

<PrimaryNav logoText="Acme" links={[{ label: 'Home', href: '/' }]} />
<MegaMenu label="Products" sections={[{ title: 'Tools', links: [{ label: 'CLI', href: '/cli' }] }]} />
<SidebarMenu items={[{ label: 'Dashboard', href: '/dashboard' }]} />
<Tabs tabs={[{ label: 'Tab 1', content: <p>Content</p> }]} />
<Breadcrumbs items={[{ label: 'Home', href: '/' }]} />
<Pagination currentPage={1} totalPages={5} onPageChange={setPage} />
<Stepper steps={[{ label: 'Step 1' }, { label: 'Step 2' }]} currentStep={0} />
<AnchorLinks items={[{ label: 'Section 1', targetId: 's1' }]} />
<SideDrawerNav links={[{ label: 'Home', href: '/' }]} />
<LanguageSelector languages={[{ code: 'en', label: 'English' }]} current="en" />
<Footer columns={[]} />

2. Hero (7 components)

import {
  HeroShell, StaticHero, SplitHero, VideoHeaderHero,
  CarouselHero, CTAOverlayHero, PatternedHero,
} from '@electroplix/components';

<StaticHero title="Welcome" subtitle="Build fast" />
<SplitHero title="Split Layout" subtitle="Left and right content" />
<CTAOverlayHero title="Call to Action" buttonText="Get Started" />
<PatternedHero pattern="grid" title="Patterned Background" />
<CarouselHero slides={[{ image: '...', title: 'Slide 1' }]} />
<VideoHeaderHero videoSrc="..." title="Video Hero" />

3. Buttons (11 components)

import {
  PrimaryButton, SecondaryButton, TertiaryButton, IconButton,
  Button, FloatingActionButton, ButtonGroup, LoadingButton,
  ShareButton, DownloadButton, PrintButton,
} from '@electroplix/components';

<PrimaryButton label="Primary" />
<SecondaryButton label="Secondary" />
<Button label="Generic" variant="primary" />
<FloatingActionButton icon="plus" fixed={false} />
<ButtonGroup buttons={[{ label: 'A' }, { label: 'B' }]} />
<LoadingButton label="Saving..." />

4. Forms (14 components)

import {
  InputField, TextAreaField, SelectDropdown, RadioGroup,
  ToggleSwitch, DateTimePicker, FileUploader, ContactForm,
  NewsletterSignup, MultiStepWizard, Captcha, AddressAutocomplete,
} from '@electroplix/components';

<InputField label="Full Name" name="name" />
<TextAreaField label="Message" name="message" />
<SelectDropdown label="Country" name="country" options={[{ value: 'us', label: 'United States' }]} />
<RadioGroup label="Plan" name="plan" options={[{ value: 'free', label: 'Free' }]} />
<ToggleSwitch label="Dark Mode" />
<DateTimePicker label="Appointment" name="date" />
<FileUploader />
<ContactForm />
<NewsletterSignup />

5. Modals (9 components)

import {
  GenericModal, ConfirmDialog, FormDialog, LoadingOverlay,
  Tooltip, ToastBanners, CookieNotice, WelcomePopup,
} from '@electroplix/components';

<GenericModal isOpen={false} onClose={() => {}}>
  <p>Modal content</p>
</GenericModal>
<ConfirmDialog isOpen={false} onClose={() => {}} onConfirm={() => {}} message="Are you sure?" />
<Tooltip text="Helpful hint"><button>Hover me</button></Tooltip>
<ToastBanners toasts={[]} />
<CookieNotice isOpen={false} onAccept={() => {}} />

6–18. Remaining Categories

  • Content — HeadingSection, Paragraph, CalloutBox, Badge, Timeline, Accordion, Divider, and more.
  • Data Display — DataTable, StatsCard, ProgressBar, Chart wrappers, and KPI blocks.
  • Ecommerce — ProductCard, ProductGrid, CartItem, CheckoutForm, OrderSummary.
  • Lists & Cards — BlogCard, FeatureCard, PricingCard, TeamCard, TestimonialCard.
  • Marketing — StaticHero variants, BannerAnnouncement, FeatureGrid, LogoCloud, CountdownTimer.
  • Media — LogoDisplay, ImageGallery, VideoPlayer, AvatarGroup.
  • Miscellaneous — ScrollToTop, SkeletonLoader, EmptyState, ErrorBoundary.
  • Onboarding — OnboardingWizard, ProgressStepper, WelcomeBanner.
  • Search — SearchBar, SearchResults, FilterPanel.
  • Site Identity — LogoDisplay, FaviconLink, BrandBadge.
  • Social — SocialShareBar, FollowButtons, SocialFeed.
  • User Accounts — UserAvatar, ProfileCard, AccountSettings, NotificationBell.
  • Blog — BlogCard, BlogGrid, TagCloud, AuthorCard, RelatedPosts.

CLI Tool

# Scaffold config + provider setup files
npx @electroplix/components init

# Get import instructions for a specific component
npx @electroplix/components add PrimaryButton

# List all 159 available components
npx @electroplix/components list

Common Pitfalls

  • Missing transpilePackages — Without transpilePackages: ['@electroplix/components'] in next.config.mjs, Next.js will throw a module resolution error.
  • ElectroplixProvider in a Server Component — The provider must be in a file with 'use client'. Always wrap it in a ClientLayout component.
  • Hooks in Server Components — All 18 use*Theme hooks require a client context. Only the @electroplix/components/config subpath is safe in Server Components.
  • Modal components in Server Components — Modal components require isOpen and onClose props from React state. Always render them in Client Components.
  • React version mismatch — The library requires react@^19.0.0. Running it alongside React 18 will cause context errors. Pin to react@19.2.5.