[vim/vim] Add 'pumopacity' option for popup menu transparency (PR #19739)

mattn

unread,

Mar 18, 2026, 1:30:55 AMMar 18

to vim/vim, Subscribed

Add the 'pumopacity' option (0-100, default 100) to control popup completion menu transparency, similar to the existing 'opacity' property for popup windows.

When pumopacity < 100, the background content shows through the popup menu. The implementation saves the background screen content before drawing the pum, then blends pum colors with the saved background using hl_pum_blend_attr() for space cells and hl_blend_attr() for text cells.

You can view, comment on, or merge this pull request online at:

https://github.com/vim/vim/pull/19739

Commit Summary

f68c55a Add 'pumopacity' option for popup menu transparency
c53009d pumopacity: move blend processing into screen_puts_len/screen_fill
4951372 pumopacity: add hl_pum_blend_attr() for correct fg/bg blending
1c91912 pumopacity: remove dead code and fix duplicate condition
80550a2 Merge remote-tracking branch 'origin/master' into add-pumopacity
b46f001 pumopacity: add tests for 'pumopacity' option

File Changes

(11 files)

M src/globals.h (13)
M src/highlight.c (132)
M src/option.h (1)
M src/optiondefs.h (4)
M src/popupmenu.c (146)
M src/proto/highlight.pro (1)
M src/proto/popupmenu.pro (1)
M src/screen.c (39)
A src/testdir/dumps/Test_pumopacity_100.dump (20)
A src/testdir/dumps/Test_pumopacity_50.dump (20)
M src/testdir/test_popup.vim (69)

Patch Links:

—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 18, 2026, 1:35:08 AMMar 18

to vim/vim, Push

@mattn pushed 1 commit.

7975e65 pumopacity: remove stray blank line in popupmenu.c

—
View it on GitHub or unsubscribe.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 18, 2026, 1:47:26 AMMar 18

to vim/vim, Push

@mattn pushed 1 commit.

ce65817 pumopacity: fix build error when FEAT_PROP_POPUP is not defined

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 18, 2026, 1:48:47 AMMar 18

to vim/vim, Push

@mattn pushed 1 commit.

35accdc pumopacity: mark blend param UNUSED in hl_pum_blend_attr()

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 18, 2026, 1:54:02 AMMar 18

to vim/vim, Push

@mattn pushed 1 commit.

095259d pumopacity: fix did_set_pumopacity() order in proto file

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 18, 2026, 2:12:50 AMMar 18

to vim/vim, Push

@mattn pushed 1 commit.

4586c6b Fix pum opacity background mismatch after window resize

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 18, 2026, 2:41:05 AMMar 18

to vim/vim, Push

@mattn pushed 1 commit.

9fa3816 pumopacity: fix option sort order in optiondefs.h

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

h_east

unread,

Mar 18, 2026, 6:07:01 AMMar 18

to vim/vim, Subscribed

h-east left a comment (vim/vim#19739)

The options for pum (popup menu) have increased quite a bit ('pumborder', 'pumheight', 'pummaxwidth', 'pumwidth'). With 'pumopacity', that makes five.

It might be time to consider introducing a new 'pumopt' option to consolidate these, similar to 'diffopt', 'completeopt', and 'statuslineopt'.

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.

Christian Brabandt

unread,

Mar 18, 2026, 3:16:30 PMMar 18

to vim/vim, Subscribed

chrisbra left a comment (vim/vim#19739)

Thanks, I tend to agree on a consolidated pumopt setting.

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 18, 2026, 9:52:19 PMMar 18

to vim/vim, Subscribed

mattn left a comment (vim/vim#19739)

Should we treat 'pumborder', 'pumheight', 'pummaxwidth', and 'pumwidth' as deprecated?

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

h_east

unread,

Mar 18, 2026, 10:00:31 PMMar 18

to vim/vim, Subscribed

h-east left a comment (vim/vim#19739)

Yes, I think we should mark it as "deprecated" in the documentation and remove it in the next or the one after that major release.

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 19, 2026, 9:39:40 PMMar 19

to vim/vim, Subscribed

mattn left a comment (vim/vim#19739)

I'm currently implementing pumopt. Please note that the addition of this option will change how pumwidth, pumheight, etc. have been handled.

When only width is specified in pumopt, height (i.e., pumheight) will be reset to its default value. In other words, to specify both pumwidth and pumheight using pumopt, you need to specify both at once:

set pumopt=width:20,height:10

I looked into the history of diffopt, statuslineopt, and completeopt, and found that all of them were introduced as single consolidated options from the start — none of them were introduced to consolidate pre-existing individual options like we are doing now.

So I plan to add a new error like e_option_is_deprecated and change pumwidth, pumheight, pumborder, pummaxwidth, and pumopacity to read-only. The values can still be read (e.g., echo &pumheight), but setting them will produce an error directing users to use pumopt instead.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 19, 2026, 10:01:23 PMMar 19

to vim/vim, Subscribed

mattn left a comment (vim/vim#19739)

I perfer to add new error e_option_is_deprecated . Anyone thought?

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 19, 2026, 10:12:59 PMMar 19

to vim/vim, Subscribed

mattn left a comment (vim/vim#19739)

Anyway I should not include the error e_option_is_deprecated in this pull-request. Should be separated.

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.

h_east

unread,

Mar 19, 2026, 11:56:55 PMMar 19

to vim/vim, Subscribed

h-east left a comment (vim/vim#19739)

I'm currently out and haven't checked the existing source codes and documentation, but wouldn't the current behavior, where pumwidth and pumheight are interacting with each other, be considered a bug? Conversely, I don't understand the reason for doing so.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 19, 2026, 11:59:08 PMMar 19

to vim/vim, Push

@mattn pushed 1 commit.

a3b46e7 Add 'pumopt' option to consolidate pum settings

—
View it on GitHub.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 20, 2026, 12:04:54 AMMar 20

to vim/vim, Subscribed

mattn left a comment (vim/vim#19739)

I looked into how other comma-separated string options behave when only some values are specified:

diffopt: set diffopt=icase resets all flags/context/algorithm to hardcoded defaults first, then only applies icase. filler, internal, etc. are all cleared.
completeopt: set completeopt=menu starts with new_flags = 0 and only sets the specified flags. All other flags are cleared.
statuslineopt: set statuslineopt=fixedheight initializes fixedheight=FALSE, maxheight=1 (defaults) first, then applies specified keys.
renderoptions: If type:directx is omitted, DirectX is disabled entirely.

All of these options reset unspecified values to their defaults. This is the standard behavior for comma-separated options in Vim. So set pumopt=width:3 resetting height to its default (0) is consistent with this pattern, not a bug.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 20, 2026, 12:11:42 AMMar 20

to vim/vim, Subscribed

mattn left a comment (vim/vim#19739)

As an aside, Vim currently has some precedent for deprecated options:

completefuzzycollect — marked as DEPRECATED in the docs. Setting it still succeeds, but cfc_flags is not referenced anywhere, so it has no effect at all.
wincolor — marked as DEPRECATED in the docs. Setting it internally redirects to winhighlight via update_wincolor(), so it still works but is redundant.

Neither of these produce an error when set. In a separate PR, I plan to introduce e_option_is_deprecated and make setting these (and the old pum options) produce an error, so that deprecated options are handled consistently.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

h_east

unread,

Mar 20, 2026, 7:30:25 AMMar 20

to vim/vim, Subscribed

h-east left a comment (vim/vim#19739)

I'm sorry, I completely misunderstood.
(I mistakenly thought you were saying that setting pumwidth clears the value of pumheight.)

When only width is specified in pumopt, height (i.e., pumheight) will be reset to its default value. In other words, to specify both pumwidth and pumheight using pumopt, you need to specify both at once:

set pumopt=width:20,height:10

Regarding the above, yes, that's how it's designed.
If you want to set it individually, you would use +=.

set pumopt+=width:3

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 20, 2026, 1:24:12 PMMar 20

to vim/vim, Subscribed

mattn left a comment (vim/vim#19739)

To clarify: this PR only adds the pumopacity option. It does not deprecate pumwidth, pumheight, pumborder, or pummaxwidth, and does not introduce pumopt.

The pumopt consolidation and the e_option_is_deprecated error will be done in a separate PR.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 20, 2026, 1:25:42 PMMar 20

to vim/vim, Subscribed

mattn left a comment (vim/vim#19739)

To clarify: this PR adds pumopacity and pumopt, but does not deprecate the existing individual options (pumwidth, pumheight, pumborder, pummaxwidth). They continue to work as before. The deprecation with e_option_is_deprecated will be handled in a separate PR.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

h_east

unread,

Mar 22, 2026, 4:31:01 AMMar 22

to vim/vim, Subscribed

h-east left a comment (vim/vim#19739)

Looking back at it, it doesn't make sense to add pumopacity when we decided to add pumopt.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 22, 2026, 6:43:11 AMMar 22

to vim/vim, Push

@mattn pushed 1 commit.

d10573a Remove 'pumopacity' option, use 'pumopt' opacity: instead

—
View it on GitHub.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 22, 2026, 6:50:48 AMMar 22

to vim/vim, Push

@mattn pushed 1 commit.

cbd0f5b Add 'pumopt' tag to doc/tags

—
View it on GitHub.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 22, 2026, 10:02:03 PMMar 22

to vim/vim, Subscribed

mattn left a comment (vim/vim#19739)

Removed pumopacity

—
Reply to this email directly, view it on GitHub.

You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 24, 2026, 11:45:25 PM (14 days ago) Mar 24

to vim/vim, Push

@mattn pushed 14 commits.

f58481f Add 'pumopacity' option for popup menu transparency
c072e40 pumopacity: move blend processing into screen_puts_len/screen_fill
31efdf1 pumopacity: add hl_pum_blend_attr() for correct fg/bg blending
97c745e pumopacity: remove dead code and fix duplicate condition
5311443 pumopacity: add tests for 'pumopacity' option
f7cf5cb pumopacity: remove stray blank line in popupmenu.c
1abdde6 pumopacity: fix build error when FEAT_PROP_POPUP is not defined
26ba5c6 pumopacity: mark blend param UNUSED in hl_pum_blend_attr()
79ef5cd pumopacity: fix did_set_pumopacity() order in proto file
5aedbfe Fix pum opacity background mismatch after window resize
c563743 pumopacity: fix option sort order in optiondefs.h
1667043 Add 'pumopt' option to consolidate pum settings
6f50ba8 Remove 'pumopacity' option, use 'pumopt' opacity: instead
b584731 Add 'pumopt' tag to doc/tags

—
View it on GitHub.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 26, 2026, 5:00:10 AM (13 days ago) Mar 26

to vim/vim, Subscribed

mattn left a comment (vim/vim#19739)

I found a behavior difference between pumheight and pumopt height:. The pum position differs — with pumopt=height:N the pum appears 2 lines lower than with set pumheight=N. Let me investigate and fix this before merging.

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 26, 2026, 5:11:18 AM (13 days ago) Mar 26

to vim/vim, Push

@mattn pushed 1 commit.

b361b48 Fix pum position offset when using 'pumopt'

—
View it on GitHub.
You are receiving this because you are subscribed to this thread.

mattn

unread,

Mar 26, 2026, 6:16:42 AM (13 days ago) Mar 26

to vim/vim, Push

@mattn pushed 1 commit.

75285fd Fix pum opacity rendering issues with border

—
View it on GitHub.
You are receiving this because you are subscribed to this thread.

mattn

unread,

5:38 AM (16 hours ago) 5:38 AM

to vim/vim, Push

@mattn pushed 1 commit.

732d7b3 Merge branch 'master' into add-pumopacity

—
View it on GitHub or unsubscribe.

You are receiving this because you are subscribed to this thread.

Christian Brabandt

unread,

4:06 PM (6 hours ago) 4:06 PM

to vim/vim, Subscribed

chrisbra left a comment (vim/vim#19739)

Thanks. I am including this now. However I noticed the two new dump files are exactly the same. Shouldn't there be a difference?

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

Christian Brabandt

unread,

4:23 PM (6 hours ago) 4:23 PM

to vim/vim, Subscribed

Closed #19739.

—
Reply to this email directly, view it on GitHub.
You are receiving this because you are subscribed to this thread.

Christian Brabandt

unread,

4:23 PM (6 hours ago) 4:23 PM

to vim/vim, Subscribed

chrisbra left a comment (vim/vim#19739)

included as of 317351c

—
Reply to this email directly, view it on GitHub, or unsubscribe.
You are receiving this because you are subscribed to this thread.

Reply all

Reply to author

Forward