Real change happens in real life when we meet in person and connect as local communities manifesting their ideas with the earth. When we help each other to step out of our bubbles at home and start building common infrastructure to meet human needs in harmony with Mother Earth.

That is why Utopia UI exists. It is a comprehensive React component library for minimalist, fast, intuitive and mobile-first map applications, as a tool for local connection and decentralized networking. We believe in maps as the perfect link between digital tools and real life action.

It can work with any backend or p2p database and any kind of data structure.

🎯 Mission

Utopia UI's mission is to provide open source building blocks to create beautiful applications with a focus on real life impact, local communities and gamification.

The building blocks are designed to allow different networks and communities to assemble their map and app for their specific needs and purpose.

It is the base of Utopia Map.

✨ Features

Core Features

Interactive Map: Leaflet-based mapping with customizable layers (Projects, Events, People, etc.)
Flexible API Interface: Works with any backend or p2p database
CRUD Operations: Create, update, delete items with full form validation
Authentication System: Complete user authentication API interface
Profile Management: Customizable profiles with multiple templates
App Shell: Responsive navigation with sidebar and top bar

Advanced Features

Permission System: Role-based access control
Gaming Elements: Quest system for user engagement
Rich Text Editing: TipTap-based markdown editor
Image Management: Upload, crop, and compress images
Tag System: Flexible categorization and filtering
Responsive Design: Mobile-first approach with PWA support

📦 Installation

Inside your React project run:

npm install utopia-ui

🚀 Getting Started

Quick Start

import { UtopiaMap, AppShell, AuthProvider } from 'utopia-ui'

function App() {
  return (
    <AuthProvider userApi={userApiInstance}>
      <AppShell appName="My Community Map">
        <UtopiaMap
          center={[50.6, 15.5]}
          zoom={5}
          height="100dvh"
          width="100dvw"
        >
          <Layer
            name="events"
            markerIcon={{
              image: "calendar.svg",
              size: 13,
            }}
            markerShape="square"
            markerDefaultColor="#700"
            data={events}
            menuIcon="calendar"
            menuColor="#700"
            menuText="events"
            itemType={itemTypeEvent}
          />
          <Layer
            name="places"
            markerIcon={{
              image: "point.svg",
            }}
            markerShape="circle"
            markerDefaultColor="#007"
            data={places}
            menuIcon="point"
            menuColor="#007"
            menuText="places"
            itemType={itemTypePlace}
          />
        </UtopiaMap>
      </AppShell>
    </AuthProvider>
  )
}

Step-by-Step Guide

Explore Examples: Check out /examples to see complete implementations
Read Documentation: Visit the docs for detailed API reference
Join Community: Connect with us on Telegram
Contribute: See the Contribution Guide for development setup

🧩 Components

Core Components

Map Components

UtopiaMap - Main interactive map component
Layer - Individual map layers with custom styling
Tags - Tag management and filtering system
Permissions - Access control wrapper

App Structure

AppShell - Main application layout
SideBar - Navigation sidebar
Content - Main content area
NavBar - Top navigation bar

Authentication

AuthProvider - Authentication context
LoginPage - User login form
SignupPage - User registration form
RequestPasswordPage - Password reset request
SetNewPasswordPage - Password reset form

Profile System

ProfileView - Display item profiles
ProfileForm - Edit item profiles
UserSettings - User account settings

Gaming

Quests - Quest system component
Modal - Gaming modal dialogs

Form Components

TextInput - Text input with validation
TextAreaInput - Multi-line text input
ComboBoxInput - Dropdown with search
RichTextEditor - Markdown editor
Autocomplete - Auto-completing input

Templates

DialogModal - Modal dialog wrapper
CardPage - Card-based page layout
ItemCard - Item display card
Tabs - Tab navigation
LoadingMapOverlay - Loading states

📚 Examples

The library includes three complete example implementations:

1. Basic Map (`/examples/1-basic-map`)

A minimal implementation showing how to set up a basic interactive map.

cd examples/1-basic-map
npm install
npm run dev

2. Static Layers (`/examples/2-static-layers`)

Demonstrates how to create predefined layers with custom icons and styling.

cd examples/2-static-layers
npm install
npm run dev

3. Tags (`/examples/3-tags`)

Shows the implementation of a tagging system for categorizing and filtering items.

cd examples/3-tags
npm install
npm run dev

📖 API Reference

UtopiaMap Component

The main map component that displays items across different layers.

Props

Prop	Type	Default	Required	Description
`height`	`string`	-	No	Height of the map container
`width`	`string`	-	No	Width of the map container
`center`	`[number, number]`	-	No	Initial map center position
`zoom`	`number`	-	No	Initial zoom level
`tags`	`Tag[]`	-	No	Array of tags to display
`geo`	`GeoJsonObject`	-	No	GeoJSON object for map data
`showFilterControl`	`boolean`	`false`	No	Show filter control
`showLayerControl`	`boolean`	`false`	No	Show layer control
`showGratitudeControl`	`boolean`	`false`	No	Show gratitude control
`showThemeControl`	`boolean`	`false`	No	Show theme control
`showZoomControl`	`boolean`	`false`	No	Show zoom control
`infoText`	`string`	-	No	Additional information text
`donationWidget`	`boolean`	`false`	No	Show donation widget
`defaultTheme`	`string`	-	No	Default theme for the map
`expandLayerControl`	`boolean`	`false`	No	Expand layer control by default

Layer Props

Property	Type	Default	Required	Description
`name`	`string`	`'places'`	No	Layer name
`menuIcon`	`string`	`'MapPinIcon'`	No	Menu icon
`menuText`	`string`	`'add new place'`	No	Menu text
`menuColor`	`string`	`'#2E7D32'`	No	Menu color
`markerIcon`	`object`	-	No	Custom marker icon configuration
`markerShape`	`'circle'` \| `'square'`	`'circle'`	No	Shape of the marker
`markerDefaultColor`	`string`	`'#777'`	No	Default marker color
`markerDefaultColor2`	`string`	`'RGBA(35, 31, 32, 0.2)'`	No	Secondary marker color
`api`	`ItemsApi`	-	No	API for layer items
`itemType`	`string`	-	No	Type of items in the layer
`userProfileLayer`	`boolean`	`false`	No	Is this a user profile layer
`customEditLink`	`string`	-	No	Custom edit link
`customEditParameter`	`string`	-	No	Custom edit parameter
`public_edit_items`	`boolean`	-	No	Allow public item editing
`listed`	`boolean`	`true`	No	Show layer in layer list

API Interfaces

ItemsApi Interface

interface ItemsApi<T> {
  getItems(filter?: Filter): Promise<T[]>
  getItem(id: string): Promise<T>
  createItem(item: Partial<T>): Promise<T>
  updateItem(id: string, item: Partial<T>): Promise<T>
  deleteItem(id: string): Promise<void>
}

UserApi Interface

interface UserApi {
  login(email: string, password: string): Promise<User>
  logout(): Promise<void>
  getCurrentUser(): Promise<User | null>
  register(userData: RegisterData): Promise<User>
  requestPasswordReset(email: string): Promise<void>
  resetPassword(token: string, password: string): Promise<void>
}

🤝 Contributing

We welcome contributions! This library is in active development and we're looking for:

Web Developers - React/TypeScript expertise
UX Designers - Mobile-first design patterns
Community Managers - Documentation and community building
Visionaries - Product direction and strategy
Artists - Icons, illustrations, and visual design

How to Contribute

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Run the test suite: npm run test:unit && npm run test:component
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

Development Guidelines

Follow the existing code style (ESLint + Prettier)
Write tests for new components
Update documentation for API changes
Use conventional commit messages
Ensure accessibility compliance

See our Contribution Guide for detailed setup instructions.

🌍 Community

This Library is in alpha stage. You are very welcome to participate in the development

Join our community and help shape the future of real-life networking apps:

Telegram: https://t.me/UtopiaMap
GitHub Discussions: Share ideas and ask questions
OpenCollective: Support the project financially

💚 Support

We are building Utopia UI as a free and open-source tool. To keep this project sustainable and accessible, we need your support:

Financial Support

Other Ways to Support

⭐ Star the repository
🐛 Report bugs and issues
📝 Improve documentation
🔗 Share the project with others
💡 Contribute ideas and feedback

📄 License

This project is licensed under GPL-3.0-only. See the LICENSE file for details.

🙏 Acknowledgments

BrowserStack - Cross-browser testing platform
OpenCollective - Transparent funding platform
All Contributors - Everyone who has contributed to this project

Built with ❤️ for real-life communities around the world

This project is tested with BrowserStack

README.md

Utopia UI