DOCSEARCHbyAlgolia
Submit Docs

Ninja Keys

repository·main·Indexed 23 days ago

https://github.com/ssleptsov/ninja-keys

A keyboard shortcut interface (Command+K / Ctrl+K) for websites, compatible with Vanilla JS, Vue, and React. It provides a searchable, navigable menu for quick actions and navigation via the <ninja-keys> custom element, supporting both flat and tree data structures through the INinjaAction interface.

Tokens
5.5K
Snippets
17
Records
28
Agent score
81%

What's inside ninja-keys

  1. Define Ninja Keys data structure

    main

    The data property of the <ninja-keys> element accepts an array of INinjaAction objects. You can use a flat structure (using parent and children IDs) or a tree structure (nested children arrays).

    const ninja = document.querySelector('ninja-keys');
ninja.data = [
  {
    id: 'Projects',
    title: 'Open Projects',
    hotkey: 'ctrl+N',
    icon: 'apps',
    section: 'Projects',
    handler: () => {
      alert('Your logic to handle');
    },
  },
  {
    id: 'Theme',
    title: 'Change theme...',
    icon: 'desktop_windows',
    children: ['Light Theme', 'Dark Theme', 'System Theme'],
    hotkey: 'ctrl+T',
    handler: () => {
      ninja.open({ parent: 'Theme' });
      return {keepOpen: true};
    },
  },
  {
    id: 'Light Theme',
    title: 'Change theme to Light',
    icon: 'light_mode',
    parent: 'Theme',
    handler: () => {
      document.documentElement.classList.remove('dark');
    },
  },
  {
    id: 'Dark Theme',
    title: 'Change theme to Dark',
    icon: 'dark_mode',
    parent: 'Theme',
    handler: () => {
      document.documentElement.classList.add('dark');
    },
  },
];

  2. Customize or hide the footer

    main

    You can replace the default footer with custom content or hide it entirely by providing a div with the slot="footer" attribute inside the <ninja-keys> component.

    <ninja-keys> 
  <div slot="footer">You can use a custom footer or empty div to hide it</div>
</ninja-keys>

  3. Implement Ninja Keys in your HTML

    main

    To use the keyboard interface, add the <ninja-keys> custom element to your HTML. You can then configure it via attributes or by assigning data to its data property via JavaScript.

    <ninja-keys> </ninja-keys>

  4. Style ninja-keys internal elements using CSS Shadow Parts

    main

    Since the component uses Shadow DOM, you can use the ::part pseudo-element to style specific internal elements. This allows for deep customization that CSS variables might not cover.

    ninja-keys::part(actions-list) {
  padding: 8px;
}
ninja-keys::part(ninja-action) {
  border-radius: 8px;
  border-left: none;
}

ninja-keys::part(ninja-selected) {
  background: rgba(51, 51, 51, 0.1);
}

ninja-keys::part(ninja-input) {
  color: #14b8a6;
}

ninja-keys::part(ninja-input)::placeholder {
  color: #f43f5e;
}

ninja-keys::part(ninja-input-wrapper) {
  background: rgba(244, 63, 93, 0.3);
}

  5. Develop Ninja Keys locally

    main

    To develop Ninja Keys locally without a bundling step, you can use the HTML files provided in the dev directory. This allows you to edit elements and see changes immediately. You need to run two commands in your terminal to enable the development environment:

    1. npm run build:watch: Monitors changes and rebuilds.
    2. npm run serve: Starts a local development server.

    This workflow enables a rapid feedback loop where you can edit and see changes without manual bundling.

    npm run build:watch
npm run serve

  7. Install Ninja Keys via NPM or CDN

    main

    You can install Ninja Keys using npm for build systems (Webpack, Rollup, Vite) or via CDN for direct usage in HTML/JS environments.

    NPM Installation:

    npm i ninja-keys

    CDN Installation: Use a module script to import the library directly from unpkg.

  8. Run Tailwind CSS processing tasks

    main

    Once the global dependencies are installed, you can use the following npm scripts to process your CSS files depending on your environment:

    • npm run tailwind: Basic usage to process your CSS for development.
    • npm run build: Processes your CSS and applies Autoprefixer for development.
    • npm run production: Processes your CSS, applies Autoprefixer, and minifies the CSS for production use.
    npm run tailwind
npm run build
npm run production

  10. Use Ninja Keys via CDN

    main

    For projects without a build system, you can include Ninja Keys using a <script type="module"> tag.

    <script type="module" src="https://unpkg.com/ninja-keys?module"></script>

<!-- Or inside a module script -->
<script type="module">
  import {NinjaKeys} from 'https://unpkg.com/ninja-keys?module';
</script>

  11. Configure icons for ninja-keys

    main

    By default, the component uses Google Material Icons. You can specify an icon by setting the mdIcon property to a Material Icon name (e.g., light_mode).

    To use custom icons, provide an svg or img string via the icon property in your action object. Ensure the SVG has the ninja-icon class applied.

    Note: If using Material Icons, ensure the Material Icons stylesheet is included in your HTML:

    <link href="https://fonts.googleapis.com/css?family=Material+Icons&display=block" rel="stylesheet">
    {
  title: 'Search projects...',
  icon: `<svg xmlns="http://www.w3.org/2000/svg" class="ninja-icon" fill="none" viewBox="0 0 24 24" stroke="currentColor">
    <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M7 8h10M7 12h4m1 8l-4-4H5a2 2 0 01-2-2V6a2 2 0 012-2h14a2 2 0 012 2v8a2 2 0 01-2 2h-3l-4 4z" />
  </svg>`,
  section: 'Projects',
}