📏 Map Size & Scaling

The size option gives you complete, flexible control over the rendered dimensions of your map. Whether you need a tiny inline widget or a massive hero graphic, you can achieve the perfect fit using either preset size strings or custom numeric scale factors.

By default, all maps render at "lg" (100% of their original, optimized base dimensions).

---

📐 Preset Sizes

For quick and predictable scaling, the library provides 8 predefined size presets. These are ideal for standard UI components and responsive design breakpoints.

Preset	Scale Multiplier	Description
"xs"	0.25x	Extra small – 25% of original dimensions
"sm"	0.5x	Small – 50% of original dimensions
"md"	0.75x	Medium – 75% of original dimensions
"lg"	1x	Large – 100% of original dimensions (Default)
"xl"	1.5x	Extra large – 150% of original dimensions
"2xl"	2x	2X Large – 200% of original dimensions
"3xl"	2.5x	3X Large – 250% of original dimensions
"4xl"	3x	4X Large – 300% of original dimensions

Example: Using a Preset

import { createMap } from "svg-world-maps";

// Renders the map at 50% of its base size
const smallMap = createMap("france", {
  size: "sm",
});

---

🔢 Custom Scale Factors

If the presets don't offer the exact precision you need, you can pass any positive number to the size option. The library will use this number as a direct multiplier for the map's base width and height.

Custom Value	Result	Use Case
0.33	Exactly one-third size	Tight sidebar widgets
0.8	20% smaller	Slightly compact layouts
1.25	25% larger	Prominent dashboard cards
1.75	75% larger	Featured content sections
2.5	Two and a half times larger	Full-width hero banners

Example: Using a Custom Number

import { createMap } from "svg-world-maps";

// Renders the map at exactly 125% of its base size
const customMap = createMap("germany", {
  size: 1.25,
});

// Renders the map at exactly 33% of its base size
const tinyMap = createMap("italy", {
  size: 0.33,
});

---

⚙️ How It Works (Under the Hood)

When you provide a size value, the library performs a simple, reliable calculation:

1. It looks up the map's base ViewportConfig (which contains the optimal width and height for that specific geography).
2. It multiplies both the width and height by your size multiplier.
3. It injects these new dimensions into the root <svg> tag.

// Example for 'usa' (Base: width 1000, height 589)
createMap("usa", { size: 2 });

// Resulting SVG attributes:
// <svg width="2000" height="1178" viewBox="0 0 1000 589" ...>

Aspect Ratio is Always Preserved

No matter what number or preset you choose, the library automatically applies preserveAspectRatio="xMidYMid meet" to the SVG. Your map will never stretch, squash, or distort. It will scale perfectly proportionally.

---

💡 Best Practices & Considerations

Responsive Design Tip

Instead of relying solely on the size option for responsiveness, consider wrapping the generated SVG in a container with CSS:

svg { width: 100%; height: auto; }

Use the size option primarily to set a maximum baseline resolution (e.g., size: "xl"), and let CSS handle the fluid scaling down to smaller screens.

Performance Note for Large Scales

Using large multipliers (like 3 or "4xl") on highly complex maps (e.g., gb with 232 regions, or usa with 51 states) will increase the physical pixel dimensions of the SVG. While SVGs are vector-based and remain crisp, extremely large dimensions can occasionally impact browser rendering performance or memory usage on low-end devices. Use 4xl judiciously.

---

📦 TypeScript Support

If you are using TypeScript, the size property is strictly typed to prevent invalid inputs:

import type { MapOptions, MapSize } from "svg-world-maps";

// ✅ Valid: Preset strings
const options1: MapOptions = { size: "md" };
const options2: MapOptions = { size: "4xl" };

// ✅ Valid: Any positive number
const options3: MapOptions = { size: 1.337 };

// ❌ Invalid: TypeScript will throw an error
const options4: MapOptions = { size: "huge" };
const options5: MapOptions = { size: -1 };