Подключение Яндекс Карты (API 3) к проекту Next.js (App Router)

31 декабря 2025 г.

Другие статьи

Dockerfile и compose.yaml для развёртывания Keystone CMS 6

Настройка аутентификации в Keystatic CMS (Local mode) в проекте Next.js

Валидация и обработка формы на сервере при помощи React-хука useActionState

Глобальное состояние в React без подключения сторонних библиотек

Пример подключения к Headless CMS (Wordpress) из приложения Next.js посредством REST API

Устранение FOUC-эффекта при использовании тёмной темы сайта в Next.js

Все статьи

AG & Dev

Подключение Яндекс Карты (API 3) к проекту Next.js (App Router)

31 декабря 2025 г.

Пример подключения Яндекс Карты (API 3) к проекту Next.js (App Router). Решение основано на официальной документации Яндекс.

Наглядная иллюстрация подключения карты (с оригинальным дизайном маркера и изображением здания) по ссылке.

Создание компонента Яндекс Карты

Создаём компонент Map с кодом добавления Яндекс Карты:

/lib/map.js

"use client";
 
import Script from "next/script";
 
const apikey = "yandex-map-api-key";
const apiurl = `https://api-maps.yandex.ru/v3/?apikey=${apikey}&lang=ru_RU`;
 
const createMap = async () => {
  await ymaps3.ready;
 
  const { YMap, YMapDefaultSchemeLayer, YMapDefaultFeaturesLayer, YMapMarker } =
    ymaps3;
 
  const coordinates = [37.603505, 55.73775];
 
  const map = new YMap(document.querySelector("#map"), {
    location: {
      center: coordinates,
      zoom: 16,
    },
    behaviors: ["drag", "pinchZoom"],
  });
 
  map.addChild(new YMapDefaultSchemeLayer());
  map.addChild(new YMapDefaultFeaturesLayer());
 
  const marker = document.querySelector("#marker");
  map.addChild(new YMapMarker({ coordinates: coordinates }, marker));
  marker.classList.remove("hidden");
};
 
export default function Map() {
  return (
    <>
      <Script src={apiurl} strategy="lazyOnload" onReady={createMap} />
 
      <section id="map" className="w-full h-112"></section>
 
      <div id="marker" className="hidden">
        <div className="text-sm">Наименование маркера</div>
      </div>
    </>
  );
}

Для подключения Яндекс Карты посредством JavaScript API необходимо получить ключ для пакета «JavaScript API» по ссылке. Ключ будет активирован в течение 15 минут после получения.

JavaScript API 3.0 работает только с ключами, у которых заполнено поле «Ограничение по HTTP Referer». Для локальной разработки в это поле необходимо добавить localhost, помимо публичного домена.

Полученный ключ нужно присвоить переменной apikey в коде выше (вместо yandex-map-api-key).

Маркер (id="marker") изначально скрыт (className="hidden"), но после подключения к карте становится видимым. По аналогии, на карту можно добавить несколько маркеров с разными названиями и по различным координатам.

Подключение компонента Яндекс Карты

Подготовленный компонент Map можно вставить в любую страницу сайта, где это необходимо:

/app/page.js

import Map from "@/lib/map";
 
export default function Page() {
  return (
    <main>
      // ...
      <Map />
      // ...
    </main>
  );
}