Tour

Быстрый старт

Минимальный пример — два шага, управление через open, current и onChange:

Live Editor

Result

Open in CodeSandbox

renderStep

renderStep — обязательный prop, отвечающий за содержимое карточки тура. Получает пять аргументов:

Аргумент	Тип	Описание
current	number	Индекс текущего шага (с нуля)
length	number	Общее количество шагов
last	boolean	true, если шаг последний
step	TourStep	Данные текущего шага (title, description, …)
goToStep	(index: number) => void	Переход к произвольному шагу

Шаги тура

Массив steps задаёт последовательность шагов. Каждый шаг описывается объектом TourStep:

Свойство	Тип	Описание
target	string | RefObject | HTMLElement	CSS-селектор, React ref или DOM-элемент для подсветки
placement	Placement	Позиция карточки относительно цели (bottom по умолчанию)
highlightOffset	number	Отступ подсветки — переопределяет общий highlightOffset
highlightBorderRadius	CSSProperties['borderRadius']	Скругление подсветки — переопределяет общий highlightBorderRadius
title	string	Заголовок карточки
description	string	Описание карточки

target

Свойство target принимает три формата:

CSS-селектор

Строка CSS-селектора — элемент ищется через document.querySelector:

Live Editor

Result

Open in CodeSandbox

React ref

Объект React.RefObject — наиболее распространённый подход:

Live Editor

Result

Open in CodeSandbox

Оверлей

Свойство withOverlay включает затемнение фона вокруг подсвеченного элемента. Цвет регулируется через overlayColor:

withOverlay

Live Editor

Result

Open in CodeSandbox

overlayColor

С помощью overlayColor можно задать произвольный цвет оверлея:

Live Editor

Result

Open in CodeSandbox

Подсветка элемента

highlightOffset задаёт отступ вокруг целевого элемента. highlightBorderRadius задаёт форму подсветки. Оба свойства можно переопределить на уровне конкретного шага:

highlightOffset

Live Editor

Result

Open in CodeSandbox

highlightBorderRadius

По умолчанию скругление вычисляется автоматически на основе border-radius целевого элемента. Можно задать явно:

Live Editor

Result

Open in CodeSandbox

Стрелка

Свойство hasTail добавляет стрелку-указатель к карточке тура. Цвет стрелки задаётся через tailColor:

Live Editor

Result

Open in CodeSandbox

Позиционирование карточки

offset задаёт отступ карточки от целевого элемента в формате [mainAxis, crossAxis]. Направление определяется свойством placement в каждом шаге:

offset

Live Editor

Result

Open in CodeSandbox

placement

Значение placement в шаге задаёт сторону размещения карточки:

Live Editor

Result

Open in CodeSandbox

Контролируемый и неконтролируемый режим

Компонент поддерживает оба режима работы:

Контролируемый

Управление состоянием вынесено наружу через open, current, onChange и onClose:

Live Editor

Result

Open in CodeSandbox

Неконтролируемый

Начальные значения задаются через defaultOpen и defaultCurrent. Компонент управляет состоянием самостоятельно:

import React, { useRef } from 'react';
import { Tour, Button } from '@salutejs/sdds-cs';

export function App() {
    const ref1 = useRef(null);
    const ref2 = useRef(null);

    const steps = [
        { target: ref1, title: 'Шаг 1 из 2', description: 'Тур открыт по умолчанию.' },
        { target: ref2, title: 'Шаг 2 из 2', description: 'Неконтролируемый режим.', placement: 'top' },
    ];

    const renderStep = (cur, length, last, step, goToStep) => (
        <div style={{ padding: '1rem', background: 'var(--surface-solid-card)', borderRadius: '0.75rem', boxShadow: '0 4px 16px rgba(0,0,0,0.12)', maxWidth: '16rem', display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
            {step.title && <strong>{step.title}</strong>}
            {step.description && <small style={{ opacity: 0.7 }}>{step.description}</small>}
            <div style={{ display: 'flex', gap: '0.5rem', marginTop: '0.25rem' }}>
                {cur > 0 && <Button size="s" view="secondary" onClick={() => goToStep(cur - 1)}>Назад</Button>}
                {last ? <Button size="s" view="default">Закрыть</Button> : <Button size="s" view="default" onClick={() => goToStep(cur + 1)}>Далее</Button>}
            </div>
        </div>
    );

    return (
        <div style={{ padding: '2rem', display: 'flex', flexDirection: 'column', gap: '4rem' }}>
            <div style={{ display: 'flex', justifyContent: 'space-between' }}>
                <Button ref={ref1} view="secondary">Элемент 1</Button>
                <Button ref={ref2} view="secondary">Элемент 2</Button>
            </div>
            <Tour defaultOpen defaultCurrent={0} steps={steps} renderStep={renderStep} />
        </div>
    );
}

Кастомная подсветка

Свойство renderHighlight заменяет стандартную подсветку произвольным React-элементом. При использовании вместе с withOverlay={false} позволяет создать полностью кастомный эффект без тёмного оверлея.

Функция получает объект TourHighlightProps:

Свойство	Тип	Описание
left	number	Координата X подсветки (уже учитывает highlightOffset)
top	number	Координата Y подсветки (уже учитывает highlightOffset)
width	number	Ширина подсветки (уже учитывает highlightOffset)
height	number	Высота подсветки (уже учитывает highlightOffset)
borderRadius	number	Скругление блока высветления

Пример с анимированным пульсирующим бордером:

Live Editor

Result

Open in CodeSandbox

Кастомный TourCard

Библиотека поставляет компонент TourCard, из которого можно собрать карточку шага с изображением, пагинацией и собственными элементами управления.

Live Editor

Result

Open in CodeSandbox

В горизонтальной ориентации contentDirection меняет взаимное расположение изображения и контента, а paginationType позволяет выбрать пагинацию точками (dot) или счётчиком (compact). Для вертикальной карточки всегда используется пагинация точками.

Тип компонента TourCard

type TourCardProps = {
    /** Ориентация карточки. @default 'horizontal' */
    orientation?: 'horizontal' | 'vertical';
    /** Расположение контента в горизонтальной карточке. @default 'row-reverse' */
    contentDirection?: 'row-reverse' | 'row';
    /** Заголовок карточки. */
    title?: string;
    /** Описание карточки. */
    description?: string;
    /** Свойства изображения: src, alt, ratio, customRatio и другие. */
    image?: ImageProps;
    /** Показывать пагинацию. @default true */
    showPagination?: boolean;
    /** Максимальное количество отображаемых точек пагинации. @default 3 */
    paginationVisibleItems?: number;
    /** Вид пагинации; compact применяется только в горизонтальной карточке. @default 'dot' */
    paginationType?: 'dot' | 'compact';
    /** Индекс текущего шага. */
    stepCurrent?: number;
    /** Общее количество шагов. */
    stepLength?: number;
    /** Функция перехода к шагу по индексу. */
    goToStep?: (index: number) => void;
    /** Кнопки навигации по шагам. */
    actionButtons?: ReactNode;
    /** Кнопка пропуска тура. */
    skipButton?: ReactNode;
    /** Показывать кнопку закрытия. @default true */
    showClose?: boolean;
    /** Обработчик закрытия тура. */
    onClose?: () => void;
    /** Вид карточки. */
    view?: string;
    /** Размер карточки. */
    size?: string;
} & HTMLAttributes<HTMLDivElement>;

API