Skip to main content

CustomControl

CustomControl

Position arbitrary custom content on the map with collision avoidance

Tags: control custom widget overlay position collision

View Demo

The CustomControl component allows you to position any custom Svelte content on the map while integrating with the positioning coordinator for collision avoidance and proper z-index stacking. It supports multiple positions, fallback positions when the primary is occupied, and priority levels for conflict resolution.

Import​

<script>
  import { CustomControl } from '@classic-homes/maps-svelte';
</script>
// React
import { CustomControl } from '@classic-homes/maps-react';

Basic Usage​

<script>
  import { Map, CustomControl } from '@classic-homes/maps-svelte';
</script>

<Map title="Custom Control Demo" center={[-122.4, 37.8]} zoom={12}>
  <CustomControl
    position="top-right"
    fallbacks={['top-left', 'bottom-right']}
    priority="normal"
    class="bg-white p-3 rounded-lg shadow"
  >
    <div>
      <h3>My Widget</h3>
      <p>Any Svelte content here</p>
    </div>
  </CustomControl>
</Map>

Props​

Component-Specific Props​

Prop Type Default Description
position ExtendedControlPosition 'top-right' Position on the map
fallbacks ExtendedControlPosition[] - Fallback positions if primary is occupied
priority 'low' | 'normal' | 'high' | 'critical' 'normal' Priority for collision resolution
zLayer 'base' | 'interactive' | 'overlay' | 'modal' 'interactive' Z-index layer
id string - Unique identifier (auto-generated if not provided)
hasExpandedState boolean false Whether the control has an expandable state
class string - Additional CSS class names
style string - Inline styles (merged with positioning styles)
children Snippet required Custom content to display

Inherited Base Map Props​

Prop Type Default Description
title string required Map title for accessibility (aria-label)
description string - Optional description for screen readers
height number | string 400 Map height in pixels or CSS value
width number | string - Map width in pixels or CSS value
loading boolean false Show loading skeleton
error string | null - Error message to display
emptyMessage string - Message shown when data is empty
theme 'light' | 'dark' | 'auto' 'auto' Theme preference
animation boolean true Enable/disable animations (respects prefers-reduced-motion)
class string - Custom CSS class for styling

Accessibility​

  • The title prop is used as aria-label for screen readers
  • Keyboard navigation support for interactive elements
  • Animations respect prefers-reduced-motion media query
  • High contrast colors in both light and dark modes
On this page