Add mixed state checkbox widget

[bmitc]

---

name: Pull Request
about: Create a pull request to help us improve
title: Add mixed state checkbox
assignees: @hoffstadt @v-ein

---

Description

I have a specific and very urgent need of a mixed state (tristate) checkbox in DearPyGui for an active project. After realizing this behavior is not built into DearPyGui and upon doing some research, I found that Dear ImGui actually has this behavior already (see references below). So this PR simply exposes that within DearPyGui.

This is my first PR to DearPyGui, so I did my best to locally build DearPyGui by running

git submodule update --init --recursive  
pip install setuptools 
python setup.py build

on macOS and then by running the testing/mixed_state_checkbox.py script, which does run and work as expected. I also added the mixed state checkbox to the demo application and tested it via the testing/run_demo.py script. This is all with Python 3.13.5. These scripts are probably not the normal way of testing DearPyGui during development, but they're the best I could manage with my limited knowledge of the DearPyGui codebase.

Disclaimer: Claude Code was used to help navigate the existing code base and build the C++ wrapper. However, I reviewed its changes and manually tested the checkbox behavior via the test script and edited the demo application.

Screenshots

Screen.Recording.2026-03-22.at.9.58.03.PM.mov

References:

1. Intermediate Checkboxes ocornut/imgui#2644 (comment)
2. https://github.com/ocornut/imgui/blob/8314fc3e5a10f7c6b670225065fce1dc8cfd396b/imgui_widgets.cpp#L1291-L1292
3. https://github.com/ocornut/imgui/blob/8314fc3e5a10f7c6b670225065fce1dc8cfd396b/docs/CHANGELOG.txt#L4872-L4873

Concerning Areas

I'm not entirely sure, but the main area I could think of is the demo application, for which I have already added the mixed_state_checkbox to, directly below the normal checkbox.

[bmitc]

@hoffstadt @v-ein I'm for some reason unable to request reviewers for this PR, so I'm tagging you here.

Also, do you know an expected timeline for this to be merged? That will help me gauge project timelines for an application that needs this behavior and to consider just creating a custom widget for this.

[v-ein]

do you know an expected timeline for this to be merged?

No estimates at the moment. I'll need to carve out some time to review the code.

Just curious, is there any reason you're adding a whole new item type instead of just adding a tristate: bool = False argument on add_checkbox? (I haven't looked at the code closely enough yet).

[v-ein]

If it fits really well, I might try to merge it before the 2.3 release, which is going to happen, ahem, soon 😂. I still need to review several PRs before making 2.3, but with my current tight schedule it's very difficult to plan anything for DPG.

[bmitc]

No estimates at the moment. I'll need to carve out some time to review the code.

Thank you! 🙇

Just curious, is there any reason you're adding a whole new item type instead of just adding a tristate: bool = False argument on add_checkbox? (I haven't looked at the code closely enough yet).

It's a good question. That seems reasonable, but there are two things that I can think of:

1. The existing checkbox has a boolean value, but a mixed state checkbox has three values, so there's a discrepancy between the two.
2. I realized it would be good to add a configuration argument to tell the mixed state checkbox which "direction" it should go when the user clicks on it. Right now, it only allows going from mixed to checked. It would be nice if it could be configured to go from mixed to unchecked, which is something I'm implementing but haven't pushed yet.