semi-design/content/plus/hotkeys/index-en-US.md

---

localeCode: en-US order: 28 category: Plus title: HotKeys icon: doc-configprovider width: 60% brief: used to facilitate the customization of keyboard shortcut

showNew: true

When to use

When it is necessary to express the usage method of shortcut key combinations to users, using the Hotkeys component can quickly render the corresponding UI elements and automatically obtain event bindings.

Demos

How to import

PinCode supported from 2.66.0

import { HotKeys } from '@douyinfe/semi-ui';

Explaination

The hotkeys only support combinations of modifier keys like Shift, Control, Meta, and Alt with other keys.

Meta corresponds to Command on macOS and Win on Windows.

When setting a shortcut that overlaps with common shortcuts like Ctrl/Meta + C, the preventDefault setting can be used to control whether the default event is triggered.

Basic Usage

Pass in key combinations via hotKeys and bind a shortcut handler function using onHotKey to respond to the action.

When pressing Ctrl + Shift + A, it opens the modal. By default, it listens on the body, making it effective globally.

values reference

It's also recommended to use the HotKeys.Keys wrapper to set hotkeys.

import React, { useState } from 'react';
import { HotKeys, Modal } from '@douyinfe/semi-ui';

function Demo() {
  const [visible, setVisible] = useState(false);
  const showDialog = () => {
      setVisible(true);
  };
  const handleOk = () => {
      setVisible(false);
  };
  const handleCancel = () => {
      setVisible(false);
  };
  const hotKeys = [HotKeys.Keys.Control, 'Shift', HotKeys.Keys.A]
  
  return (
    <div>
      <HotKeys hotKeys={hotKeys} onHotKey={showDialog} ></HotKeys>
      <Modal
          title="Dialog"
          visible={visible}
          onOk={handleOk}
          onCancel={handleCancel}
      >
          This is the Modal opened by hotkey: {hotKeys.join('+')}.
      </Modal>
    </div>
  );
}

Custom content

Set the characters through content

import React, { useState } from 'react';
import { HotKeys, Modal } from '@douyinfe/semi-ui';

function Demo() {
  const [visible, setVisible] = useState(false);
  const showDialog = () => {
      setVisible(true);
  };
  const handleOk = () => {
      setVisible(false);
  };
  const handleCancel = () => {
      setVisible(false);
  };
  const hotKeys = [HotKeys.Keys.Control, 'Shift', HotKeys.Keys.B]
  
  return (
    <div>
      <HotKeys hotKeys={hotKeys} onHotKey={showDialog} content={['Ctrl', 'Shift', 'B']}></HotKeys>
      <Modal
          title="Dialog"
          visible={visible}
          onOk={handleOk}
          onCancel={handleCancel}
      >
          This is the Modal opened by hotkey: {hotKeys.join('+')}.
      </Modal>
    </div>
  );
}

Replace the element through render

import React, { useState } from 'react';
import { HotKeys, Modal, Tag } from '@douyinfe/semi-ui';

function Demo() {
  const [visible, setVisible] = useState(false);
  const showDialog = () => {
      setVisible(true);
  };
  const handleOk = () => {
      setVisible(false);
  };
  const handleCancel = () => {
      setVisible(false);
  };
  const hotKeys = [HotKeys.Keys.Control, HotKeys.Keys.R]
  
  const newHotKeys = <Tag>Press Ctrl+R to Open Modal</Tag>
  return (
    <div>
      <HotKeys hotKeys={hotKeys} onHotKey={showDialog} render={newHotKeys}></HotKeys>
      <Modal
          title="Dialog"
          visible={visible}
          onOk={handleOk}
          onCancel={handleCancel}
      >
          This is the Modal opened by hotkey: {hotKeys.join('+')}.
      </Modal>
    </div>
  );
}

prevent Default event

Control the default event by setting preventDefault.

import React, { useState } from 'react';
import { HotKeys, Modal } from '@douyinfe/semi-ui';

function Demo() {
  const [visible, setVisible] = useState(false);
  const showDialog = () => {
      setVisible(true);
  };
  const handleOk = () => {
      setVisible(false);
  };
  const handleCancel = () => {
      setVisible(false);
  };
  const hotKeys = [HotKeys.Keys.Meta, HotKeys.Keys.S]

  return (
    <div>
      <HotKeys hotKeys={hotKeys} onHotKey={showDialog} preventDefault></HotKeys>
      <br />
      <HotKeys hotKeys={[HotKeys.Keys.Control, HotKeys.Keys.S]} onHotKey={showDialog} preventDefault></HotKeys>
      <Modal
          title="Dialog"
          visible={visible}
          onOk={handleOk}
          onCancel={handleCancel}
      >
          This is the Modal opened by hotkey: {'Meta/Control + S'}.
      </Modal>
    </div>
  );
}

change the DOM element the listener is mounted on

The hotkey is listened to on the body by default, through getListenerTarget

import React, { useState, useRef } from 'react';
import { HotKeys, Input, Modal } from '@douyinfe/semi-ui';

function Demo() {
  const hotKeys = ["Control", "q"]
  const [visible, setVisible] = useState(false);
  const showDialog = () => {
      setVisible(true);
  };
  const handleOk = () => {
      setVisible(false);
  };
  const handleCancel = () => {
      setVisible(false);
  };

  const inputRef = useRef(null);
  return (
    <div>
      <Input ref={inputRef} placeholder='test for target'></Input>
      <HotKeys hotKeys={hotKeys} onHotKey={showDialog} 
        getListenerTarget={() => inputRef.current}>
      </HotKeys>
      <Modal
          title="Dialog"
          visible={visible}
          onOk={handleOk}
          onCancel={handleCancel}
      >
          This is the Modal opened by hotkey: {hotKeys.join('+')}.
      </Modal>
    </div>
  );
}

API Reference

HotKeys

Property	Instructions	type	Default
className	class name	string
content	Set the characters	string[]	-
getListenerTarget	change the DOM element the listener is mounted on	() => HTMLElement	document.body
hotKeys	Define keyboard shortcut，values	KeyboardEvent.key[]	-
onClick	callback that clicking triggers	() => void	-
onHotKey	callback that hotKeys triggers	(e: KeyboardEvent) => void	-
preventDefault	Whether to prevent the default behavior of the shortcut	boolean	false
render	Replace the element	() => ReactNode | ReactNode
style	style	CSSProperties

Design Tokens

Related Material