VKUI Documentation

VKUI is a library of adaptive React components designed for web application development. It is based on the official VK design system.

Key Features

• Adaptivity: Components automatically adjust to screen sizes (smartphones, tablets, and computers).
• Multiplatform Support: VKUI mimics both iOS and Android styles to maintain a consistent look with vk.com and m.vk.com across different environments.
• Color Schemes: Built-in support for both light and dark themes to ensure accessibility.

Design Resources

You can use the official open design libraries available in the VK Figma Community:

• VKUI Common Library [Beta]: The primary component library for Android and desktop.
• VKUI iOS Library: Components specifically for iOS, including ready-to-use screen templates.

The DateRangeInput component allows users to select a start and end date via manual text input or a calendar picker.

Note: This component is designed for tablets and desktops. Its behavior on mobile devices is not guaranteed.

If you need a standalone calendar for range selection, use CalendarRange. If you need a single date and time input with a popup calendar, use DateInput.

<DateRangeInput />

The ChipsSelect component allows users to select multiple values from a dropdown list. Each selected item is rendered as an individual Chip component. You can provide a predefined list of options via the options prop.

<ChipsSelect
  options={[
    { value: 'red', label: 'Красный' },
    { value: 'blue', label: 'Синий' },
    { value: 'green', label: 'Зеленый' },
  ]}
  placeholder="Выберите значение"
/>

The DateInput component allows users to enter a date manually or select one via a calendar popup.

Important Usage Notes:

• Platform Support: This component is designed for tablets and desktops. Its behavior is not guaranteed on mobile devices.
• Alternatives:
  • For date range selection (with a popup calendar), use DateRangeInput.
  • For a standalone calendar component (without an input field), use Calendar.

<DateInput />

The Search component supports standard React controlled and uncontrolled patterns:

• Uncontrolled mode: Do not pass the value prop. Use defaultValue to set an initial value.
• Controlled mode: Use the value and onChange props to manage the state manually.

// Uncontrolled state
<Search defaultValue="Поиск" />;

// Controlled state
const [value, setValue] = React.useState('Поиск');

<Search value={value} onChange={(event) => setValue(event.target.value)} />;

When a field header is composite (contains multiple elements), use FormItem subcomponents to manage layout and accessibility:

• <FormItem.Top>: A wrapper for the composite header that handles alignment and spacing.
• <FormItem.TopLabel>: Renders the field label. It defaults to a <label> tag if htmlFor is provided. You can override the tag via the Component prop.
• <FormItem.TopAside>: Renders additional content (like character counters) to the right of the label.

const id = React.useId()

return (
  <FormItem
    top={
      <FormItem.Top>
        <FormItem.TopLabel htmlFor={id}>Дополнительная информация</FormItem.TopLabel>
        <FormItem.TopAside>0/100</FormItem.TopAside>
      </FormItem.Top>
    }
  >
    <Textarea id={id} name="about" />
  </FormItem>
);

Async Loading Indicators

To notify screen reader users during data fetching, use the fetching prop. You can customize the announcement text using:

• fetchingInProgressLabel: Default is "Список опций загружается...".
• fetchingCompletedLabel: Default is "Опций загружено: ${options.length}".

Fixing Selection Visibility

In older versions, some screen readers (like NVDA) struggled to identify the selected option because the input value was reset on blur.

Solution: Use the accessible flag.

• In v8+, accessible={true} is the default and is highly recommended.
• Do not disable this flag, as it will be removed in v9.

The usePagination hook provides full control over the pagination logic and item array. Use this hook when you need:

• A non-standard pagination UI.
• Integration with custom logic.
• Complex transition animations.

The hook returns an array of items representing the pages and ellipsis markers (e.g., [1, 'start-ellipsis', 4, 5, 6, 'end-ellipsis', 10]).

const items = usePagination({
  totalPages: 10,
  currentPage: 5,
});

// items → [1, 'start-ellipsis', 4, 5, 6, 'end-ellipsis', 10]

return (
  <nav>
    {items.map((item) =>
      item === 'start-ellipsis' || item === 'end-ellipsis' ? (
        <span key={item}>...</span>
      ) : (
        <button key={item}>{item}</button>
      ),
    )}
  </nav>
);