> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hudhud.sa/llms.txt
> Use this file to discover all available pages before exploring further.

# Displaying a Map

> Render vector maps using MapLibre-compliant styles and the KSA road network.

Hudhud provides vector tile styles optimized for performance and local accuracy in Saudi Arabia. These styles are compatible with any MapLibre GL JS (web) or native SDK (mobile).

## Available Styles

Hudhud provides two standard base styles, both offering full bilingual support and high-performance vector rendering.

<CardGroup cols={2}>
  <Card title="Light Variant" icon="sun">
    `variant=light` (default) - Optimized for day-time navigation.
  </Card>

  <Card title="Dark Variant" icon="moon">
    `variant=dark` - Optimized for low-light and night-time use.
  </Card>
</CardGroup>

## Simple Implementation

The fastest way to get a map running is to include the library and initialize it with your **Publishable Key**.

```html theme={null}
<!DOCTYPE html>
<html>
<head>
    <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.23.0/dist/maplibre-gl.css" />
    <script src="https://unpkg.com/maplibre-gl@5.23.0/dist/maplibre-gl.js"></script>
    <style>#map { position: absolute; top: 0; bottom: 0; width: 100%; }</style>
</head>
<body>
    <div id="map"></div>
    <script>
        // --- 1. CONFIGURATION ---
        const API_KEY  = 'pk_YOUR_PUBLISHABLE_KEY';
        const MAP_ID   = 'YOUR_MAP_ID';
        const VARIANT  = 'light'; // light | dark
        const LANGUAGE = 'ar';    // ar | en

        // --- 2. INITIALIZE ---
        // Required for Arabic labels
        maplibregl.setRTLTextPlugin('https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.3.0/dist/mapbox-gl-rtl-text.js', true);

        const map = new maplibregl.Map({
            container: 'map',
            style: `https://b.hudhud.sa/v1/maps/styles/${MAP_ID}?variant=${VARIANT}&lang=${LANGUAGE}&api_key=${API_KEY}`,
            center: [45.0792, 23.8859], // Center of Saudi Arabia
            zoom: 5
        });
    </script>
</body>
</html>
```

## Interactive Switching (Advanced)

For applications that need to switch themes or languages dynamically without a page reload, you can use the `map.setStyle()` method.

<Expandable title="View Interactive Demo Code">
  ```html theme={null}
  <!DOCTYPE html>
  <html lang="en">
  <head>
      <meta charset="UTF-8">
      <meta name="viewport" content="width=device-width, initial-scale=1.0">
      <title>Hudhud Maps - Live Demo</title>
      <link rel="stylesheet" href="https://unpkg.com/maplibre-gl@5.23.0/dist/maplibre-gl.css" />
      <script src="https://unpkg.com/maplibre-gl@5.23.0/dist/maplibre-gl.js"></script>
      <style>
          body { margin: 0; padding: 0; font-family: sans-serif; }
          #map { position: absolute; top: 0; bottom: 0; width: 100%; }
          .controls {
              position: absolute; top: 10px; left: 10px; z-index: 1;
              background: white; padding: 10px; border-radius: 4px;
              display: flex; gap: 10px;
          }
      </style>
  </head>
  <body>
      <div class="controls">
          <select id="variant"><option value="light">Light Mode</option><option value="dark">Dark Mode</option></select>
          <select id="lang"><option value="ar">Arabic</option><option value="en">English</option></select>
      </div>
      <div id="map"></div>
      <script>
          const API_KEY = 'pk_YOUR_PUBLISHABLE_KEY';
          const MAP_ID  = 'YOUR_MAP_ID';
          const BASE_URL = 'https://b.hudhud.sa/v1/maps/styles';

          maplibregl.setRTLTextPlugin('https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.3.0/dist/mapbox-gl-rtl-text.js', true);

          function getStyleUrl(variant, lang) {
              return `${BASE_URL}/${MAP_ID}?variant=${variant}&lang=${lang}&api_key=${API_KEY}`;
          }

          const map = new maplibregl.Map({
              container: 'map',
              style: getStyleUrl('light', 'ar'),
              center: [45.0792, 23.8859], // Center of Saudi Arabia
              zoom: 5
          });

          const updateStyle = () => map.setStyle(getStyleUrl(document.getElementById('variant').value, document.getElementById('lang').value));
          document.getElementById('variant').addEventListener('change', updateStyle);
          document.getElementById('lang').addEventListener('change', updateStyle);
      </script>
  </body>
  </html>
  ```
</Expandable>

<Warning>
  **RTL Plugin Requirement**: If you see Arabic labels rendered with detached letters or in reverse order, ensure the RTL plugin URL is correct and that `setRTLTextPlugin` is called before the map is initialized.
</Warning>

## Integration Resources

<CardGroup cols={2}>
  <Card title="Authentication" icon="shield-check" href="/guides/authentication">
    Learn how to use your Publishable Key securely in the frontend.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/maps/get-map-styles">
    See the full list of query parameters for the Styles API.
  </Card>
</CardGroup>
