GothamJS: The Complete Front-End UI Framework

Seamlessly integrating components, routing, state management, and transitions

A comprehensive front-end UI framework that handles everything from component rendering to routing and smooth transitions with minimal configuration.

GothamJS is an all-inclusive React framework that unifies UI components, navigation, state management, and transitions into one cohesive system. Built by Nitrogen Labs, GothamJS eliminates the need to piece together multiple libraries, providing developers with a consistent, integrated solution for all front-end UI needs.

✨ Key Features

• Unified Component Library: Beautifully designed, fully customizable UI components with consistent styling and behavior
• Seamless Routing & Transitions: Built-in navigation system with smooth page transitions and animations
• Integrated State Management: Flux-based state handling that connects directly to your UI components
• Form System: Complete form components with validation, error handling, and accessibility features
• Theming & Styling: Light/dark mode support and customizable design system based on Tailwind CSS
• Responsive Design: Mobile-first components that adapt beautifully to any screen size
• Internationalization: Built-in i18n support for multilingual applications
• Authentication Flows: Ready-to-use authentication UI components and routing guards
• Icon Library: Complete Lucide React icon set available for use throughout your application

🚀 Getting Started

# Install GothamJS
npm install @nlabs/gothamjs

# Or with yarn
yarn add @nlabs/gothamjs

Create your first GothamJS application:

import { createRoot } from 'react-dom/client';
import { Gotham } from '@nlabs/gothamjs';

// Define your application configuration
const config = {
  app: {
    name: 'my-awesome-app',
    title: 'My Awesome App'
  },
  routes: [
    {
      path: '/',
      element: <HomePage />,
      props: {
        topBar: {
          logo: <img src="/logo.png" alt="Logo" />,
          menu: [
            { label: 'Sign In', url: '/signin' },
            { label: 'Sign Up', url: '/signup' }
          ]
        }
      }
    }
  ]
};

// Render your application
const root = createRoot(document.getElementById('app'));
root.render(<Gotham config={config} />);

🧩 Components

GothamJS provides a rich set of components to accelerate your development:

Icons

GothamJS includes the complete Lucide React icon library, providing you with over 1000+ beautifully designed, customizable icons that follow a consistent design language.

Why Lucide React?

• Consistent Design: All icons follow the same design principles and stroke width
• Customizable: Easy to customize size, color, stroke width, and other properties
• Accessible: Built with accessibility in mind, including proper ARIA attributes
• Tree Shakeable: Only the icons you import are included in your bundle
• TypeScript Support: Full type definitions for all icons
• Active Development: Regularly updated with new icons and improvements

Quick Reference

• Icon Gallery: Browse all available icons
• Documentation: Lucide React documentation
• GitHub: Lucide project on GitHub

Usage

import { Camera, Heart, Star, Settings, LucideLoader } from '@nlabs/gothamjs/icons';

const MyComponent = () => (
  <div>
    <Camera size={24} />
    <Heart size={24} color="red" />
    <Star size={24} fill="yellow" />
    <Settings size={24} />
    <LucideLoader size={24} /> {/* Use LucideLoader to avoid conflict with GothamJS Loader component */}
  </div>
);

Icon Properties

All Lucide React icons support these common properties:

<Camera
  size={24}           // Icon size in pixels
  color="currentColor" // Icon color
  strokeWidth={2}     // Stroke width
  fill="none"         // Fill color
  className="my-icon" // CSS classes
/>

Note: The Loader icon from Lucide React is exported as LucideLoader to avoid conflicts with GothamJS's Loader component.

Form Components

import { Form, TextField, Button } from '@nlabs/gothamjs';
import { z } from 'zod';

// Define your form schema with Zod
const loginSchema = z.object({
  email: z.string().email('Please enter a valid email'),
  password: z.string().min(8, 'Password must be at least 8 characters')
});

const LoginForm = () => (
  <Form
    schema={loginSchema}
    onSubmit={(data) => console.log('Form submitted:', data)}
  >
    <TextField
      name="email"
      label="Email"
      placeholder="Enter your email"
    />
    <TextField
      name="password"
      type="password"
      label="Password"
      placeholder="Enter your password"
    />
    <Button
      type="submit"
      variant="contained"
      color="primary"
      label="Sign In"
    />
  </Form>
);

UI Components

import { Button, Notify, Loader } from '@nlabs/gothamjs';

// Stylish button with multiple variants
<Button
  variant="contained" // 'contained', 'outlined', or 'text'
  color="primary"     // 'primary', 'secondary', 'success', 'error', etc.
  size="md"           // 'sm', 'md', or 'lg'
  onClick={handleClick}
>
  Click Me
</Button>

// Show notifications
<Notify
  message="Operation completed successfully!"
  severity="success" // 'success', 'info', 'warning', or 'error'
  autoHideDuration={5000}
/>

// Loading indicator
<Loader size="md" />

📊 State Management

GothamJS uses ArkhamJS, a Flux implementation, for state management:

import { useFlux } from '@nlabs/arkhamjs-utils-react';
import { GothamActions } from '@nlabs/gothamjs';

const MyComponent = () => {
  const flux = useFlux();

  // Navigate to a new route
  const handleNavigation = () => {
    GothamActions.navGoto('/dashboard');
  };

  // Show a notification
  const showNotification = () => {
    GothamActions.notify({
      message: 'This is a notification',
      severity: 'info'
    });
  };

  // Show/hide loading indicator
  const startLoading = () => {
    GothamActions.loading(true, 'Loading data...');

    // After operation completes
    setTimeout(() => {
      GothamActions.loading(false);
    }, 2000);
  };

  return (
    <div>
      <Button onClick={handleNavigation} label="Go to Dashboard" />
      <Button onClick={showNotification} label="Show Notification" />
      <Button onClick={startLoading} label="Start Loading" />
    </div>
  );
};

🌐 Routing

GothamJS simplifies routing with React Router integration:

const config = {
  routes: [
    {
      path: '/',
      element: <HomeView />,
      props: {
        // Props passed to the component
      }
    },
    {
      path: '/dashboard',
      element: <DashboardView />,
      authenticate: true, // Requires authentication
      children: [
        {
          path: 'profile',
          element: <ProfileView />
        },
        {
          path: 'settings',
          element: <SettingsView />
        }
      ]
    }
  ]
};

🔒 Authentication

GothamJS provides built-in authentication support:

const config = {
  // Define authentication check function
  isAuth: () => Boolean(localStorage.getItem('token')),
  routes: [
    {
      path: '/protected',
      element: <ProtectedView />,
      authenticate: true // This route requires authentication
    }
  ]
};

🌍 Internationalization

Easy internationalization with i18next:

const config = {
  translations: {
    en: {
      greeting: 'Hello, {{name}}!',
      buttons: {
        submit: 'Submit'
      }
    },
    es: {
      greeting: '¡Hola, {{name}}!',
      buttons: {
        submit: 'Enviar'
      }
    }
  }
};

// In your component
import { t } from 'i18next';

const MyComponent = () => (
  <div>
    <h1>{t('greeting', { name: 'User' })}</h1>
    <Button label={t('buttons.submit')} />
  </div>
);

🎨 Theming

GothamJS supports light/dark mode and custom themes:

const config = {
  displayMode: 'dark', // 'light' or 'dark'
  theme: {
    // Custom theme properties
    colors: {
      primary: '#3f51b5',
      secondary: '#f50057'
    }
  }
};

🔧 Configuration

GothamJS is highly configurable:

const config = {
  app: {
    name: 'my-app',
    title: 'My Application',
    logo: '/logo.svg',
    titleBarSeparator: '|'
  },
  baseUrl: '',
  storageType: 'local', // 'local' or 'session'
  middleware: [customMiddleware],
  stores: [customStore],
  onInit: () => {
    // Custom initialization logic
    console.log('App initialized');
  }
};

💼 Why Choose GothamJS?

• UI Consistency: Create visually cohesive applications with a unified design language
• Developer Experience: Spend less time wiring up libraries and more time building features
• Reduced Bundle Size: One framework instead of multiple libraries means optimized bundle size
• Seamless Transitions: Built-in animations and transitions between routes and UI states
• Accessibility: Components designed with accessibility in mind from the start
• Rapid Development: Go from concept to production with significantly less boilerplate code
• TypeScript Support: Full type definitions for enhanced developer experience

📚 Learn More

Visit our official documentation for comprehensive guides, API references, and examples.

📦 Related Packages

• @nlabs/arkhamjs - Flux implementation
• @nlabs/lex - Build and development tools

📄 License

GothamJS is MIT licensed.