Hướng Dẫn Sử Dụng Mapbox Trong Next.js

1. Giới thiệu về Mapbox

Mapbox là một nền tảng bản đồ mạnh mẽ, cung cấp API để hiển thị bản đồ, tìm kiếm địa điểm, chỉ đường và nhiều tính năng khác. So với Google Maps, Mapbox linh hoạt hơn và hỗ trợ tùy chỉnh giao diện bản đồ một cách sâu sắc.

Trong bài viết này, chúng ta sẽ tìm hiểu cách tích hợp Mapbox vào Next.js 15 để hiển thị bản đồ tương tác.

2. Cài đặt Mapbox trong Next.js

Bước 1: Tạo tài khoản và lấy API Key

Truy cập Mapbox và tạo tài khoản. Sau khi đăng nhập, bạn sẽ nhận được Mapbox Access Token, token này sẽ cần để gọi API.

Bước 2: Cài đặt thư viện Mapbox

Chạy lệnh sau để cài đặt mapbox-gl (thư viện Mapbox cho JavaScript):

npm install mapbox-gl

3. Hiển thị bản đồ trong Next.js

Tạo một component Map.tsx để hiển thị bản đồ:

📌 components/Map.tsx

"use client";

import { useEffect, useRef } from "react";
import mapboxgl from "mapbox-gl";

mapboxgl.accessToken = process.env.NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN || "";

const Map = () => {
  const mapContainerRef = useRef<HTMLDivElement | null>(null);
  const mapRef = useRef<mapboxgl.Map | null>(null);

  useEffect(() => {
    if (!mapContainerRef.current || mapRef.current) return;

    // Khởi tạo bản đồ
    mapRef.current = new mapboxgl.Map({
      container: mapContainerRef.current,
      style: "mapbox://styles/mapbox/streets-v12", // Chọn kiểu bản đồ
      center: [106.8272, 10.8231], // Tọa độ [longitude, latitude] (VD: TP. HCM)
      zoom: 10, // Độ thu phóng
    });

    return () => mapRef.current?.remove();
  }, []);

  return <div ref={mapContainerRef} className="w-full h-[500px]" />;
};

export default Map;

4. Sử dụng component Map trong trang Next.js

Mở app/page.tsx (hoặc app/page.js nếu dùng JavaScript) và import component Map:

📌 app/page.tsx

import Map from "@/components/Map";

export default function Home() {
  return (
    <main className="flex flex-col items-center justify-center h-screen">
      <h1 className="text-2xl font-bold mb-4">Bản đồ Mapbox trong Next.js</h1>
      <Map />
    </main>
  );
}

5. Bảo mật API Key với biến môi trường

Trong file .env.local, thêm API Key của bạn:

NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN=your_mapbox_access_token_here

❗ Lưu ý: NEXT_PUBLIC_ là bắt buộc để biến môi trường có thể được sử dụng trên client-side.

6. Thêm marker và popup vào bản đồ

Nếu bạn muốn thêm marker (điểm đánh dấu) vào bản đồ, cập nhật file Map.tsx:

📌 Cập nhật Map.tsx với marker

"use client";

import { useEffect, useRef } from "react";
import mapboxgl from "mapbox-gl";

mapboxgl.accessToken = process.env.NEXT_PUBLIC_MAPBOX_ACCESS_TOKEN || "";

const Map = () => {
  const mapContainerRef = useRef<HTMLDivElement | null>(null);
  const mapRef = useRef<mapboxgl.Map | null>(null);

  useEffect(() => {
    if (!mapContainerRef.current || mapRef.current) return;

    // Khởi tạo bản đồ
    mapRef.current = new mapboxgl.Map({
      container: mapContainerRef.current,
      style: "mapbox://styles/mapbox/streets-v12",
      center: [106.8272, 10.8231], // Tọa độ TP. HCM
      zoom: 10,
    });

    // Thêm marker vào vị trí trung tâm
    const marker = new mapboxgl.Marker()
      .setLngLat([106.8272, 10.8231])
      .setPopup(new mapboxgl.Popup().setHTML("<h3>TP. Hồ Chí Minh</h3>"))
      .addTo(mapRef.current);

    return () => mapRef.current?.remove();
  }, []);

  return <div ref={mapContainerRef} className="w-full h-[500px]" />;
};

export default Map;

🔹 Giải thích:

• Marker: Thêm điểm đánh dấu vào tọa độ center.
• Popup: Hiển thị thông tin khi click vào marker.

7. Tùy chỉnh giao diện bản đồ

Bạn có thể thay đổi theme của bản đồ bằng cách thay đổi style trong mapboxgl.Map:

style: "mapbox://styles/mapbox/dark-v11", // Chế độ tối

🔹 Một số kiểu bản đồ có sẵn:

• mapbox://styles/mapbox/streets-v12 (Mặc định)
• mapbox://styles/mapbox/outdoors-v12 (Dành cho bản đồ địa hình)
• mapbox://styles/mapbox/satellite-v9 (Chế độ vệ tinh)
• mapbox://styles/mapbox/dark-v11 (Chế độ tối)

8. Xử lý sự kiện click trên bản đồ

Bạn có thể thêm sự kiện click để lấy tọa độ khi người dùng nhấp vào bản đồ:

mapRef.current?.on("click", (e) => {
  console.log("Tọa độ:", e.lngLat);
});

Khi người dùng click vào bản đồ, tọa độ sẽ được log ra console.

9. Khi nào nên dùng Mapbox?

✅ Nên dùng Mapbox khi:

• Cần tùy chỉnh giao diện bản đồ theo thiết kế riêng.
• Muốn có hiệu suất tốt hơn so với Google Maps.
• Cần hiển thị bản đồ trên ứng dụng Next.js hoặc React.

❌ Không nên dùng nếu:

• Bạn chỉ cần hiển thị bản đồ đơn giản và không muốn thiết lập API Key.
• Bạn cần sử dụng nhiều dữ liệu bản đồ từ Google Maps.

10. Kết luận

Tích hợp Mapbox vào Next.js giúp bạn xây dựng bản đồ tương tác với hiệu suất cao và giao diện đẹp. Qua bài viết này, bạn đã biết cách:
✅ Cài đặt Mapbox trong Next.js
✅ Hiển thị bản đồ với center và zoom tùy chỉnh
✅ Thêm marker và popup vào bản đồ
✅ Xử lý sự kiện click để lấy tọa độ

Bạn có thể mở rộng ứng dụng với các tính năng như tìm kiếm địa điểm, chỉ đường, hoặc tích hợp API khác của Mapbox để tạo trải nghiệm bản đồ nâng cao.

Tài liệu tham khảo:

https://docs.mapbox.com