Add custom option slot to KDropdownMenu and update documentation

[vtushar06]

Description

Exposes UiMenu's existing option scoped slot through KDropdownMenu, allowing consumers to customize the rendering of each menu item.

Issue addressed

Addresses #1200

Before/after screenshots

Changelog

• Description: New option scoped slot on KDropdownMenu. Use <template #option="{ option }"> to customize how each menu item renders (icon placement, color, text size, etc.).
• Products impact: new API
• Addresses: [KDropdownMenu] Enable options customization #1200.
• Components: KDropdownMenu
• Breaking: no
• Impacts a11y: no
• **Guidance:**Use #option when the options array config isn't sufficient. Existing behavior is unchanged when the slot is not used.

Steps to test

1. yarn dev → go to KDropdownMenu docs page
2. Verify the new "Custom option slot" section appears with a working live example
3. Verify the API Slots table lists both header and option
4. Verify all existing examples still work (no regressions)
5. yarn test and yarn lint — both pass

Testing checklist

• Contributor has fully tested the PR manually
• If there are any front-end changes, before/after screenshots are included
• Critical and brittle code paths are covered by unit tests
• The change is described in the changelog section above

Reviewer guidance

• Is the code clean and well-commented?
• Are there tests for this change?

[learning-equality-bot]

👋 Thanks for contributing!

We will assign a reviewer within the next two weeks. In the meantime, please ensure that:

• You ran pre-commit locally
• All issue requirements are satisfied
• The contribution is aligned with our Contributing guidelines. Pay extra attention to Using generative AI. Pull requests that don't follow the guidelines will be closed.

We'll be in touch! 😊

[Copilot]

Pull request overview

This PR exposes UiMenu’s existing scoped option slot through KDropdownMenu, enabling consumers to fully customize how each dropdown item is rendered, and updates the docs + visual tests accordingly.

Changes:

• Forward #option scoped slot from KDropdownMenu to the underlying UiMenu.
• Add a new docs section + example demonstrating custom option rendering.
• Add a new visual regression example for the custom option slot.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
lib/KDropdownMenu/index.vue	Adds forwarding for an option scoped slot into UiMenu.
lib/KDropdownMenu/tests/components/KDropdownMenuVisualTest.vue	Registers a new visual test case for the custom option slot example.
examples/KDropdownMenu/CustomOption.vue	New example demonstrating #option usage to render icons + styled labels.
docs/pages/kdropdownmenu.vue	Adds a “Custom option slot” section and links it in the page sub-nav.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

Percy Visual Test Results

Percy Dashboard: View Detailed Report

Environment:

• Node.js Version: 18.x
• OS: Ubuntu-latest

Instructions for Reviewers:

• Click on the Percy Dashboard link to view detailed visual diffs.
• Review the visual changes highlighted in the report.
• Approve or request changes based on the visual differences.

[AlexVelezLl]

Thanks @vtushar06! Code changes look good, and visual tests show no regression. Just want to check-in something before merging:

@MisRob, There is a rather small problem with just exposing this option as is, the thing is that the node we pass through the slot cannot infer the 100% of the available height, for example, even if we add height: 100%, the slot does not take the whole height:

To get the full height, we will also need to set a min-height: 40px (or 2.5 rem) to the node that passes through the slot, and this will work fine unless we change the min-height of the UiMenuOption, in which case, we would have an unintended regression that would be difficult to detect. It seems a way to solve this could be by modifying this node to have a class like, so that any node we pass as slot gets the whole height without harcoding the min-height value:

  .ui-menu-option {
    display: flex;
    flex-direction: column;
    & > * {
      flex-grow: 1;
    }
  }

We might want to do this, or any other workaround in the scope of this PR, or if you consider this min height is something that might not change, then it is okay to leave it as it is right now.

[vtushar06]

Thanks for catching this @AlexVelezLl, You're right our current example hardcodes height: 40px which is fragile. Your proposed CSS fix is the correct approach. I think we should update .ui-menu-option in UiMenuOption.vue to use display: flex; flex-direction: column with & > * { flex-grow: 1 }, and remove the hardcoded height from the example. This makes slot content fill the full height correctly without depending on a specific pixel value.

[MisRob]

Thanks, that's good consideration. I'm fine with that solution @AlexVelezLl :) Within the Keen-related limitations we work with, it feels like the most robust solution we can do now.

[MisRob]

As for documentation example code, I recommend we keep it as concise and straightforward as possible, and we show only parts relevant to the new slot. The documentation component provides API to customize what template / script /css we show to a reader, e.g. for template (note the use of ...) :

<KButton
  text="Options"
  hasDropdown
>
  <template #menu>
    <KDropdownMenu
      :options="options"
       ...
    >
      <template #option="{ option }">
        <div style="display: flex; align-items: center; height: 40px; padding: 0 16px">
          <KIcon
            :icon="option.icon"
            :style="{ color: option.color, marginInlineEnd: '8px' }"
          />
          <span :style="{ color: option.color }">{{ option.label }}</span>
        </div>
      </template>
    </KDropdownMenu>
  </template>
</KButton>

Script can be adjusted too.

Not that it'd be a big deal at this single place ~ it's just that if we don't consider it for new examples, documentation tends to grow a lot and in my opinion is then harder to navigate & understand. Readers can get full code by clicking GitHub icon if needed.

[MisRob]

For the script we should just show:

export default {
  data() {
    return {
      options: [
        { label: 'Edit', value: 'edit', icon: 'edit', color: null },
        { label: 'Delete', value: 'delete', icon: 'delete', color: '#e74c3c' },
      ],
    };
  },
};

Other 80% of the current content would be irrelevant.

@vtushar06 to be clear, you don't need to change how the example component is implemented. This is only about what we show in the docs. You can search for examples how to achieve it or if it's not clear, @AlexVelezLl or I will help :) Thanks!

[MisRob]

And finally, please don't use hardcoded color: '#e74c3c. Even in code examples, it's important to stick to KDS colors too ~ this is where new KDS users learn.

[vtushar06]

Hi @MisRob, So I've made all the fixes based on the your feedback. The height thing now works way better with flexbox instead of hardcoding pixels, so it won't break if things change. I have switched to KDS color tokens instead of those random hex codes, which keeps everything looking consistent. And the docs example now shows the real way you'd actually use it.
Please let me know if any further improvement needed.

[AlexVelezLl]

Thanks a lot @vtushar06! Code changes look good, visual tests show no visual regression, just a couple of observations before merging this PR 👐.

[vtushar06]

Hey @AlexVelezLl and @MisRob, Made all the latest fixes, swapped out the manual div + KIcon + span pattern for KLabeledIcon in both the example component and the docs snippet, which also takes care of the template expression evaluation issue. Also added :hideOnClick="true" to the DocsExample. Let me know if there's anything else to tweak!

[AlexVelezLl]

Thanks @vtusharc06! Apologies for the late reply. Just one last thing. Could you add some padding to the example options? These examples are expected to serve as the point of reference for how people should use them, so it's important to keep the examples clean. Thanks!

[vtushar06]

Hey @AlexVelezLl, I have added padding and also centered the content which makes examples clean,
have a look and please let me know if any more changes required.

[AlexVelezLl]

Thanks a lot @vtushar06! LGTM!