React UI

Using Mappedin JS with your own map requires a Pro license. Try a demo map for free or refer to the Pricing page for more information.

The @mappedin/react-ui package provides a small, unopinionated component library for Mappedin JS. It offers pre-built, customizable UI components commonly used in mapping applications, such as search bars, floor selectors and zoom controls. These components can be styled using built-in themes or custom CSS.

info

The React UI components are designed to work with both @mappedin/mappedin-js and @mappedin/react-sdk. Refer to the Using React guide for information on setting up a React project with Mappedin JS.

Installation

The React UI package can be installed from npm using either npm or Yarn.

With NPM:

npm install @mappedin/react-ui

With Yarn:

yarn add @mappedin/react-ui

Getting Started

To use the React UI components, import the desired components and a theme. Components are imported individually from their respective paths within the package. A theme stylesheet must also be imported to provide styling.

// Import components
import { Search } from '@mappedin/react-ui/components/search';
import { FloorSelector } from '@mappedin/react-ui/components/floor-selector';

// Import a theme
import '@mappedin/react-ui/themes/mappedin-light.css';

// Render the component in an app
export const App: React.FC = () => {
    return (
        <div>
            <Search {...props} />
            <FloorSelector {...props} />
        </div>
    );
};

Themes

The React UI package includes built-in themes that can be imported to style all components consistently. Two default themes are available:

Light Theme

The light theme provides a clean, bright appearance suitable for most applications:

import '@mappedin/react-ui/themes/mappedin-light.css';

Dark Theme

The dark theme offers a darker color scheme for applications that prefer a dark mode aesthetic:

import '@mappedin/react-ui/themes/mappedin-dark.css';

Headless Mode

For applications that require complete control over styling, the React UI components can be used in headless mode. This mode imports only the functional CSS required for the components to work, leaving all visual styling to be defined by the application.

// Import only functional CSS to use components unstyled
import '@mappedin/react-ui/themes/basic.css';

Styling

Components can be styled using CSS class selectors. All React UI components use class names prefixed with .mappedin__ to avoid conflicts with other styles.

/**
 * Add custom styles by overriding CSS variables.
 */
globalStyles(`
	:root {
		--mappedin-font-family: 'Comic Sans MS', sans-serif;
		--mappedin-color-primary-1:rgb(255, 196, 0);
		--mappedin-color-background-1:rgb(73, 129, 185);
		--mappedin-color-neutral-1: rgb(194, 226, 255);
		--mappedin-color-neutral-2: rgb(102, 102, 102);
		--mappedin-color-text-1: rgb(255, 255, 255);
	}
`);

/**
 * Add custom styles by targetting class names.
 */
globalStyles(`
	.mappedin__icon--magnifying-glass {
		color: white;
	}
`);

/**
 * Add custom styles and props using the `props` API.
 */
const customSearchProps: React.ComponentProps<typeof Search>['props'] = {
	wrapper: {
		className: 'custom-search-wrapper-class',
	},
	locationList: {
		wrapper: {
			className: 'custom-location-list-wrapper-class',
			style: {
				backgroundColor: 'rgb(73, 164, 255)',
			},
		},
		listItemName: {
			style: {
				fontFamily: 'Times New Roman',
			},
		},
	},
};

This approach allows for targeted styling of specific elements within the components while maintaining the overall structure and functionality.

Custom Props

The React UI components support passing custom props to inner elements using the props property. This enables adding custom attributes such as tabIndex, aria-* attributes, or other HTML properties to the underlying DOM elements.

// Pass props down to inner elements using `props`
const App: React.FC = () => (
    <SearchBar
        props={{
            wrapper: {
                tabIndex: 0,
            },
        }}
    />
);

Available Components

The React UI package provides several components for building mapping interfaces. Refer to the React UI API Reference for detailed information on each component's props and usage.

FloorSelector

The FloorSelector component allows users to switch between different floors of a multi-level venue. It displays the available floors and handles floor change events.

LocationList

The LocationList component displays a list of locations within a venue. It can be used to show search results, categories, or any collection of venue locations.

Search

The Search component provides a complete search interface for finding locations within a venue. It combines a search input with results display and handles user interactions.

SearchBar

The SearchBar component provides a standalone search input field. It handles text input and can be used independently or as part of a custom search implementation.

ZoomControls

The ZoomControls component provides buttons to zoom in and out of the map. It offers a simple interface for users to adjust the map's zoom level.

Example

The following CodeSandbox demonstrates how to use the Mappedin React UI components with their default settings using a light theme.