0
# Tile Providers
1

2
Built-in tile provider functions for popular map services with customization options and high-DPI support. Providers generate tile URLs for different map services and styles, enabling custom map appearances without external dependencies.
3

4
## Capabilities
5

6
### OpenStreetMap Provider
7

8
Default tile provider using OpenStreetMap tiles.
9

10
```typescript { .api }
11
/**
12
 * OpenStreetMap tile provider (default)
13
 * @param x - Tile X coordinate
14
 * @param y - Tile Y coordinate  
15
 * @param z - Zoom level
16
 * @returns Tile URL string
17
 */
18
function osm(x: number, y: number, z: number): string;
19
```
20

21
**Usage Example:**
22

23
```tsx
24
import React from "react";
25
import { Map } from "pigeon-maps";
26
import { osm } from "pigeon-maps/providers";
27

28
function OSMMap() {
29
  return (
30
    <Map 
31
      height={400} 
32
      center={[50.879, 4.6997]} 
33
      zoom={11}
34
      provider={osm}
35
    />
36
  );
37
}
38
```
39

40
### Stamen Toner Provider
41

42
High-contrast black and white map style from Stamen Design.
43

44
```typescript { .api }
45
/**
46
 * Stamen Toner tile provider with high-DPI support
47
 * @param x - Tile X coordinate
48
 * @param y - Tile Y coordinate
49
 * @param z - Zoom level
50
 * @param dpr - Device pixel ratio (optional, defaults to 1)
51
 * @returns Tile URL string with appropriate resolution
52
 */
53
function stamenToner(x: number, y: number, z: number, dpr?: number): string;
54
```
55

56
**Usage Example:**
57

58
```tsx
59
import React from "react";
60
import { Map } from "pigeon-maps";
61
import { stamenToner } from "pigeon-maps/providers";
62

63
function TonerMap() {
64
  return (
65
    <Map 
66
      height={400} 
67
      center={[50.879, 4.6997]} 
68
      zoom={11}
69
      provider={stamenToner}
70
      dprs={[1, 2]} // Enable high-DPI tiles
71
    />
72
  );
73
}
74
```
75

76
### Stamen Terrain Provider
77

78
Terrain map style with elevation shading from Stamen Design.
79

80
```typescript { .api }
81
/**
82
 * Stamen Terrain tile provider with high-DPI support
83
 * @param x - Tile X coordinate
84
 * @param y - Tile Y coordinate
85
 * @param z - Zoom level
86
 * @param dpr - Device pixel ratio (optional, defaults to 1)
87
 * @returns Tile URL string with appropriate resolution
88
 */
89
function stamenTerrain(x: number, y: number, z: number, dpr?: number): string;
90
```
91

92
**Usage Example:**
93

94
```tsx
95
import React from "react";
96
import { Map } from "pigeon-maps";
97
import { stamenTerrain } from "pigeon-maps/providers";
98

99
function TerrainMap() {
100
  return (
101
    <Map 
102
      height={400} 
103
      center={[50.879, 4.6997]} 
104
      zoom={11}
105
      provider={stamenTerrain}
106
      dprs={[1, 2]} // Enable high-DPI tiles
107
    />
108
  );
109
}
110
```
111

112
### MapTiler Provider
113

114
Configurable provider for MapTiler cloud service with multiple map styles.
115

116
```typescript { .api }
117
/**
118
 * MapTiler provider factory function
119
 * @param apiKey - MapTiler API key
120
 * @param map - Map style identifier (optional, defaults to 'streets')
121
 * @returns Tile provider function with high-DPI support
122
 */
123
function maptiler(apiKey: string, map?: string): TileProvider;
124

125
type TileProvider = (x: number, y: number, z: number, dpr?: number) => string;
126
```
127

128
**Available Map Styles:**
129
- `'streets'` (default): Standard street map
130
- `'satellite'`: Satellite imagery
131
- `'hybrid'`: Satellite with street labels
132
- `'terrain'`: Terrain visualization
133
- `'topo'`: Topographic map
134

135
**Usage Examples:**
136

137
```tsx
138
import React from "react";
139
import { Map } from "pigeon-maps";
140
import { maptiler } from "pigeon-maps/providers";
141

142
// Basic streets map
143
function MapTilerStreets() {
144
  const provider = maptiler('your-api-key');
145
  
146
  return (
147
    <Map 
148
      height={400} 
149
      center={[50.879, 4.6997]} 
150
      zoom={11}
151
      provider={provider}
152
      dprs={[1, 2]}
153
    />
154
  );
155
}
156

157
// Satellite imagery
158
function MapTilerSatellite() {
159
  const provider = maptiler('your-api-key', 'satellite');
160
  
161
  return (
162
    <Map 
163
      height={400} 
164
      center={[50.879, 4.6997]} 
165
      zoom={11}
166
      provider={provider}
167
      dprs={[1, 2]}
168
    />
169
  );
170
}
171

172
// Multiple styles with switcher
173
function MapTilerWithStyleSwitcher() {
174
  const [style, setStyle] = useState('streets');
175
  const provider = maptiler('your-api-key', style);
176
  
177
  return (
178
    <div>
179
      <div style={{ marginBottom: '10px' }}>
180
        <button onClick={() => setStyle('streets')}>Streets</button>
181
        <button onClick={() => setStyle('satellite')}>Satellite</button>
182
        <button onClick={() => setStyle('terrain')}>Terrain</button>
183
      </div>
184
      <Map 
185
        height={400} 
186
        center={[50.879, 4.6997]} 
187
        zoom={11}
188
        provider={provider}
189
        dprs={[1, 2]}
190
      />
191
    </div>
192
  );
193
}
194
```
195

196
### Stadia Maps Provider
197

198
Configurable provider for Stadia Maps service with multiple styles.
199

200
```typescript { .api }
201
/**
202
 * Stadia Maps provider factory function
203
 * @param style - Map style identifier (optional, defaults to 'alidade_smooth')
204
 * @returns Tile provider function with high-DPI support
205
 */
206
function stadiamaps(style?: string): TileProvider;
207
```
208

209
**Available Styles:**
210
- `'alidade_smooth'` (default): Clean, smooth street map
211
- `'alidade_smooth_dark'`: Dark theme version
212
- `'outdoors'`: Outdoor/hiking focused map
213
- `'stamen_terrain'`: Terrain visualization
214
- `'stamen_toner'`: High-contrast black and white
215
- `'stamen_watercolor'`: Artistic watercolor style
216

217
**Usage Examples:**
218

219
```tsx
220
import React from "react";
221
import { Map } from "pigeon-maps";
222
import { stadiamaps } from "pigeon-maps/providers";
223

224
// Default smooth style
225
function StadiaSmooth() {
226
  const provider = stadiamaps();
227
  
228
  return (
229
    <Map 
230
      height={400} 
231
      center={[50.879, 4.6997]} 
232
      zoom={11}
233
      provider={provider}
234
      dprs={[1, 2]}
235
    />
236
  );
237
}
238

239
// Dark theme
240
function StadiaDark() {
241
  const provider = stadiamaps('alidade_smooth_dark');
242
  
243
  return (
244
    <Map 
245
      height={400} 
246
      center={[50.879, 4.6997]} 
247
      zoom={11}
248
      provider={provider}
249
      dprs={[1, 2]}
250
    />
251
  );
252
}
253

254
// Outdoors style
255
function StadiaOutdoors() {
256
  const provider = stadiamaps('outdoors');
257
  
258
  return (
259
    <Map 
260
      height={400} 
261
      center={[50.879, 4.6997]} 
262
      zoom={11}
263
      provider={provider}
264
      dprs={[1, 2]}
265
    />
266
  );
267
}
268
```
269

270
## Custom Providers
271

272
### Creating Custom Providers
273

274
You can create custom tile providers by implementing the `TileProvider` interface:
275

276
```typescript { .api }
277
type TileProvider = (x: number, y: number, z: number, dpr?: number) => string;
278
```
279

280
**Custom Provider Examples:**
281

282
```tsx
283
// Simple custom provider
284
function customTileProvider(x, y, z) {
285
  return `https://mytileserver.com/${z}/${x}/${y}.png`;
286
}
287

288
// Provider with API key
289
function createCustomProvider(apiKey) {
290
  return (x, y, z, dpr = 1) => {
291
    const resolution = dpr >= 2 ? '@2x' : '';
292
    return `https://api.example.com/tiles/${z}/${x}/${y}${resolution}.png?key=${apiKey}`;
293
  };
294
}
295

296
// Provider with subdomain rotation
297
function createRotatingProvider(subdomains = ['a', 'b', 'c']) {
298
  return (x, y, z) => {
299
    const subdomain = subdomains[(x + y) % subdomains.length];
300
    return `https://${subdomain}.tiles.example.com/${z}/${x}/${y}.png`;
301
  };
302
}
303

304
// Usage
305
function CustomProviderMap() {
306
  const myProvider = createCustomProvider('my-api-key');
307
  
308
  return (
309
    <Map 
310
      height={400} 
311
      center={[50.879, 4.6997]} 
312
      zoom={11}
313
      provider={myProvider}
314
    />
315
  );
316
}
317
```
318

319
## High-DPI Support
320

321
### Device Pixel Ratio
322

323
Many providers support high-DPI displays through the `dpr` parameter:
324

325
```typescript { .api }
326
// Standard resolution (dpr = 1)
327
provider(x, y, z, 1) // → "...tile.png"
328

329
// High resolution (dpr = 2)  
330
provider(x, y, z, 2) // → "...tile@2x.png"
331
```
332

333
### Configuring High-DPI
334

335
```tsx
336
import React from "react";
337
import { Map } from "pigeon-maps";
338
import { stamenToner } from "pigeon-maps/providers";
339

340
function HighDPIMap() {
341
  return (
342
    <Map 
343
      height={400} 
344
      center={[50.879, 4.6997]} 
345
      zoom={11}
346
      provider={stamenToner}
347
      dprs={[1, 2]} // Enable both standard and high-DPI tiles
348
    />
349
  );
350
}
351
```
352

353
### Automatic Detection
354

355
The map automatically detects device pixel ratio and requests appropriate tiles when `dprs` array is provided.
356

357
## Provider Switching
358

359
### Dynamic Provider Switching
360

361
```tsx
362
import React, { useState } from "react";
363
import { Map } from "pigeon-maps";
364
import { osm, stamenToner, stamenTerrain, maptiler } from "pigeon-maps/providers";
365

366
function ProviderSwitcher() {
367
  const [currentProvider, setCurrentProvider] = useState('osm');
368
  
369
  const providers = {
370
    osm: osm,
371
    toner: stamenToner,
372
    terrain: stamenTerrain,
373
    maptiler: maptiler('your-api-key')
374
  };
375
  
376
  return (
377
    <div>
378
      <div style={{ marginBottom: '10px' }}>
379
        {Object.keys(providers).map(key => (
380
          <button 
381
            key={key}
382
            onClick={() => setCurrentProvider(key)}
383
            style={{ 
384
              margin: '2px',
385
              backgroundColor: currentProvider === key ? '#007bff' : '#f8f9fa'
386
            }}
387
          >
388
            {key.toUpperCase()}
389
          </button>
390
        ))}
391
      </div>
392
      <Map 
393
        height={400} 
394
        center={[50.879, 4.6997]} 
395
        zoom={11}
396
        provider={providers[currentProvider]}
397
        dprs={[1, 2]}
398
      />
399
    </div>
400
  );
401
}
402
```
403

404
## Attribution Requirements
405

406
Different tile providers have different attribution requirements:
407

408
### OpenStreetMap
409
```html
410
© OpenStreetMap contributors
411
```
412

413
### Stamen Design
414
```html
415
Map tiles by Stamen Design, under CC BY 3.0. Data by OpenStreetMap, under ODbL.
416
```
417

418
### MapTiler
419
```html
420
© MapTiler © OpenStreetMap contributors
421
```
422

423
### Setting Attribution
424

425
```tsx
426
import React from "react";
427
import { Map } from "pigeon-maps";
428
import { maptiler } from "pigeon-maps/providers";
429

430
function AttributedMap() {
431
  return (
432
    <Map 
433
      height={400} 
434
      center={[50.879, 4.6997]} 
435
      zoom={11}
436
      provider={maptiler('your-api-key')}
437
      attribution={
438
        <span>
439
          © <a href="https://www.maptiler.com/">MapTiler</a> © <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors
440
        </span>
441
      }
442
    />
443
  );
444
}
445
```
446

447
## Performance Considerations
448

449
- Tile providers with CDN support (like Stamen, MapTiler) typically load faster
450
- High-DPI tiles are larger files but provide better quality on high-density displays
451
- Consider caching policies of different tile services
452
- Some providers have rate limits or require API keys
453
- Subdomain rotation can improve parallel download performance