The header works only inside CdsLayout — outside the layout it renders nothing and warns about it in the console. The content of the header is laid out by CdsToolbar, and the bottom bar of the application is built by CdsFooter.

Variations

Separator

The header overlaps the scrollable content, so its edge is worth marking: bordered draws a border, elevated casts a shadow. The shadow is more noticeable and suits long lists better, the border suits calm pages.

Sandbox Storybook

<script setup lang="ts">
import {
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsRadio,
  CdsRadioGroup,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const separator = ref('bordered');
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="separator" direction="horizontal" hide-details>
      <CdsRadio value="none" label="Без разделителя" />
      <CdsRadio value="bordered" label="Граница" />
      <CdsRadio value="elevated" label="Тень" />
    </CdsRadioGroup>

    <div class="h-[240px]">
      <CdsLayout container>
        <CdsHeader :bordered="separator === 'bordered'" :elevated="separator === 'elevated'">
          <CdsToolbar>
            <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
          </CdsToolbar>
        </CdsHeader>

        <CdsMain>
          <CdsPage padding>
            <div class="flex flex-col gap-2">
              <div v-for="n in 6" :key="n" class="rounded-200 bg-surface-secondary p-4 text-content-primary">
                Блок {{ n }}
              </div>
            </div>
          </CdsPage>
        </CdsMain>
      </CdsLayout>
    </div>
  </div>
</template>

Height

The height comes from the content: the layout measures the header and reserves exactly as much space as it takes. The height prop is an initial estimate before the first measurement: set the expected height so the content does not jump on mount.

Sandbox Storybook

<script setup lang="ts">
import {
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsRadio,
  CdsRadioGroup,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const size = ref(56);
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="size" direction="horizontal" hide-details>
      <CdsRadio :value="40" label="40 px" />
      <CdsRadio :value="56" label="56 px" />
      <CdsRadio :value="80" label="80 px" />
    </CdsRadioGroup>

    <div class="h-[240px]">
      <CdsLayout container>
        <CdsHeader bordered :height="size">
          <CdsToolbar :style="{ height: size + 'px' }">
            <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
          </CdsToolbar>
        </CdsHeader>

        <CdsMain>
          <CdsPage padding>
            <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
              Контент начинается ровно под шапкой: макет замерил её и зарезервировал {{ size }} px.
            </div>
          </CdsPage>
        </CdsMain>
      </CdsLayout>
    </div>
  </div>
</template>

Color

The bg-color prop paints the background of the header with a palette alias, color paints the text and the icons inside. If only the background is set, the text color is picked to be contrasting automatically.

Sandbox Storybook

<script setup lang="ts">
import {
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsRadio,
  CdsRadioGroup,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const bgColor = ref('default');
</script>

<template>
  <div class="flex flex-col gap-4">
    <CdsRadioGroup v-model="bgColor" direction="horizontal" hide-details>
      <CdsRadio value="default" label="Цвет темы" />
      <CdsRadio value="indigo" label="indigo" />
      <CdsRadio value="teal" label="teal" />
      <CdsRadio value="neutral" label="neutral" />
    </CdsRadioGroup>

    <div class="h-[240px]">
      <CdsLayout container>
        <CdsHeader :bg-color="bgColor === 'default' ? undefined : bgColor">
          <CdsToolbar>
            <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
          </CdsToolbar>
        </CdsHeader>

        <CdsMain>
          <CdsPage padding>
            <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Содержимое страницы</div>
          </CdsPage>
        </CdsMain>
      </CdsLayout>
    </div>
  </div>
</template>

Floating mode

The reveal prop hides the header when scrolling down and brings it back when scrolling up — on long lists this gives the screen to the content. The reveal-offset prop sets the zone near the top of the page where the header stays in place. The @reveal event reports the change of visibility, and moving the keyboard focus inside a hidden header brings it back.

Sandbox Storybook

<script setup lang="ts">
import { CdsHeader, CdsLayout, CdsMain, CdsPage, CdsToolbar, CdsToolbarTitle } from '@central-design-system/components';
import { ref } from 'vue';

const revealed = ref(true);
</script>

<template>
  <div class="h-[320px]">
    <CdsLayout container>
      <CdsHeader reveal elevated :reveal-offset="120" @reveal="revealed = $event">
        <CdsToolbar>
          <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding>
          <div class="mb-2 text-content-secondary">Шапка сейчас {{ revealed ? 'видна' : 'скрыта' }}</div>
          <div class="flex flex-col gap-2">
            <div v-for="n in 20" :key="n" class="rounded-200 bg-surface-secondary p-4 text-content-primary">
              Блок {{ n }}
            </div>
          </div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>

Visibility

The model-value prop removes the header entirely: the layout stops reserving space for it and the content takes the freed height. This is a handy way to hide the header in full-screen modes — document viewing, a presentation.

Sandbox Storybook

<script setup lang="ts">
import { CdsHeader, CdsLayout, CdsMain, CdsPage, CdsToolbar, CdsToolbarTitle } from '@central-design-system/components';
</script>

<template>
  <div class="grid grid-cols-1 gap-4 sm:grid-cols-2">
    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">Шапка видна</span>
      <div class="h-[200px]">
        <CdsLayout container>
          <CdsHeader bordered>
            <CdsToolbar>
              <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
            </CdsToolbar>
          </CdsHeader>

          <CdsMain>
            <CdsPage padding>
              <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Контент страницы</div>
            </CdsPage>
          </CdsMain>
        </CdsLayout>
      </div>
    </div>

    <div class="flex flex-col gap-1">
      <span class="text-content-secondary">:model-value="false"</span>
      <div class="h-[200px]">
        <CdsLayout container>
          <CdsHeader :model-value="false" bordered>
            <CdsToolbar>
              <CdsToolbarTitle>Заголовок приложения</CdsToolbarTitle>
            </CdsToolbar>
          </CdsHeader>

          <CdsMain>
            <CdsPage padding>
              <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">
                Шапка скрыта — контент поднялся на её место
              </div>
            </CdsPage>
          </CdsMain>
        </CdsLayout>
      </div>
    </div>
  </div>
</template>

Guidelines

Storybook

Scenarios

Application header

The basic set: a menu button, a logo, the title in CdsToolbarTitle and the actions on the right. CdsToolbarTitle stretches and pushes the left and the right groups to the edges, so no extra spacers are needed.

Sandbox Storybook

<script setup lang="ts">
import {
  CdsAvatar,
  CdsBadge,
  CdsFunctionalButton,
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
</script>

<template>
  <div class="h-[280px]">
    <CdsLayout container>
      <CdsHeader bordered :height="64">
        <CdsToolbar class="h-[64px]">
          <CdsFunctionalButton icon="menu" class="mr-2" aria-label="Открыть навигацию" />
          <CdsAvatar icon="company" class="mr-2" />
          <CdsToolbarTitle>Портал закупок</CdsToolbarTitle>

          <CdsFunctionalButton icon="search" aria-label="Поиск" />
          <CdsBadge :content="3">
            <CdsFunctionalButton icon="notification" aria-label="Уведомления" />
          </CdsBadge>
          <CdsAvatar icon="user" class="ml-2" />
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Содержимое страницы</div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>

Header with tabs

Two CdsToolbar components in a row turn the header into a two-level one: the name of the section on top, CdsTabs with the subsections below. The tabs stay on the screen together with the header, so you can switch from any point of the list.

Sandbox Storybook

<script setup lang="ts">
import {
  CdsHeader,
  CdsLayout,
  CdsMain,
  CdsPage,
  CdsTab,
  CdsTabs,
  CdsToolbar,
  CdsToolbarTitle
} from '@central-design-system/components';
import { ref } from 'vue';

const tab = ref('active');
</script>

<template>
  <div class="h-[280px]">
    <CdsLayout container>
      <CdsHeader bordered :height="96">
        <CdsToolbar>
          <CdsToolbarTitle>Закупки</CdsToolbarTitle>
        </CdsToolbar>
        <CdsToolbar no-gutter="start">
          <CdsTabs v-model="tab">
            <CdsTab value="active">Активные</CdsTab>
            <CdsTab value="draft">Черновики</CdsTab>
            <CdsTab value="archive">Архив</CdsTab>
          </CdsTabs>
        </CdsToolbar>
      </CdsHeader>

      <CdsMain>
        <CdsPage padding>
          <div class="rounded-200 bg-surface-secondary p-4 text-content-primary">Вкладка: {{ tab }}</div>
        </CdsPage>
      </CdsMain>
    </CdsLayout>
  </div>
</template>

API

Props

Name	Type	Default	Description
bgColor	string | undefined	—	Background color of the component
bordered	boolean | undefined	false	Shows the border.
color	string | undefined	—	Component color
elevated	boolean | undefined	false	Shows the shadow.
height	string | number | undefined	50	Height of the element.
modelValue	boolean | undefined	true	Visibility of the element in the layout.
reveal	boolean | undefined	false	Floating mode: the element appears/hides on scroll.
revealOffset	number | undefined	250	Scroll threshold (px) up to which the floating element stays visible.
theme	string | undefined	—	Component theme

Events

Name	Type	Description
focusin	[event: FocusEvent]	Focus moved inside the header.
reveal	[value: boolean]	Visibility of the floating header has changed.

Slots

Name	Type	Description
default	any	Content of the header (CdsToolbar and others).