clip: a small C++ library for the system clipboard

One API over three unrelated native clipboard systems

clip is a C++ library for copying and retrieving content to and from the clipboard, or pasteboard, on Windows, macOS and Linux. The copyright line reads David Capello, 2015 to 2026, and the licence is MIT.

The reason this library exists is that the three operating systems do not offer the same thing. Windows has a clipboard with a format registry and a documented limit on how many formats can be registered at once. macOS has the pasteboard with named types. X11 has a selection model in which the clipboard is a property transfer to a third-party process rather than a service owned by the system. Writing that three times is unpleasant, and writing it once behind a stable interface is what clip does.

The feature set is deliberately small, and the project states it plainly for Windows, macOS and Linux X11. You can copy and paste UTF-8 text, you can copy and paste user-defined data, and you can copy and paste RGB and RGBA images. That last one has a detail worth knowing: the library uses non-premultiplied alpha RGB values, which is not the convention every image library uses, so mixing clip with an image pipeline requires converting.

The repository layout reflects the split directly. There are platform files named clip_win.cpp, clip_win.h, clip_win_bmp.cpp, clip_win_wic.cpp, clip_osx.h, clip_osx.mm and clip_x11.cpp, plus shared headers clip.h, clip_base.h, clip_common.h and clip_lock_impl.h, and a clip_none.cpp for platforms with no implementation. The Objective-C++ extension on the macOS file is a hint about how that backend is written, since the pasteboard is an Objective-C API.

set_text and get_text, and how the copy is locked

The basic usage is two calls. The example in the project documentation shows a complete program:

#include "clip.h"
#include <iostream>

int main() {
  clip::set_text("Hello World");

  std::string value;
  clip::get_text(value);
  std::cout << value << "\n";
}

The one-way calls are the convenience layer. The real interface is the lock, and the custom format example is where it appears:

#include "clip.h"

int main() {
  clip::format my_format =
    clip::register_format("com.appname.FormatName");

  int value = 32;
  std::string str = "Alternative text for value 32";

  clip::lock l;
  l.clear();
  l.set_data(clip::text_format(), str.c_str(), str.size());
  l.set_data(my_format, (const char*)&value, sizeof(int));
}

The pattern is worth reading carefully because it is how you write more than one format in a single clipboard transaction. A clip::lock object is created, its data is cleared so the clipboard starts empty, and then set_data is called once per format with a pointer and a byte count. Because the writes happen under one lock, a reader on the other side sees a clipboard with both the text and the custom payload, rather than two separate states.

The custom format is registered with a namespaced name, com.appname.FormatName in the example, which is the convention the platform clipboard systems expect. Registering it returns a clip::format value that is then used as the key for set_data.

The text format is available as clip::text_format(), so a custom format does not replace the text one. The example deliberately writes both, and gives the payload a human-readable alternative string, which is the kind of choice that pays off later when a user pastes into an application that does not know the custom format.

The compile flags decide which platform code is built

clip is built with CMake, and the build is controlled by a small set of feature flags that the project documents one by one.

CLIP_ENABLE_IMAGE turns on the support for copying and pasting images, and the flag points at the two example programs, put_image.cpp and show_image.cpp, that exercise it. CLIP_ENABLE_LIST_FORMATS is Windows only, and it enables the clip::lock::list_formats() function together with the list_clip_formats example. CLIP_EXAMPLES compiles the examples directory, CLIP_TESTS compiles the tests directory, and CLIP_INSTALL generates the installation rules for CMake.

There is one more flag, CLIP_X11_WITH_PNG, which is for Linux and X11 only and enables image support through the libpng library on that platform. That is the platform-specific cost of images on Linux, and it is worth noting that it is not the same as the general CLIP_ENABLE_IMAGE flag, so enabling images on Linux involves two separate decisions.

The dependencies follow from the same list. On Linux you need libx11-dev or libX11-devel to copy and paste at all, because the X11 implementation is the backend, and libpng-dev or libpng-devel in addition to copy and paste images. Those are named in the project documentation as the platform specifics for Linux.

The CMake configuration lives in a CMakeLists.txt at the root, with a clip-config.cmake.in file for the installed package config. The examples directory has its own CMakeLists.txt, and there are example programs for copying, pasting, the hello world case, the integer format, listing clipboard formats, putting an image and showing an image.

Custom formats and the 32-bit versus 64-bit trap

The platform notes contain one piece of advice that is easy to skim past and expensive to ignore. If two versions of your application, 32-bit and 64-bit, can run at the same time, you should avoid storing data types that could change depending on the platform, and size_t is the example given.

The reason is that a custom format is identified by name and read back as raw bytes, so the writer and the reader have to agree on the layout. If one build writes a size_t as eight bytes and another reads it as four, the value is silently wrong rather than an error. The custom format example sidesteps this by storing a plain int with an explicit sizeof(int), and by pairing the binary payload with a text alternative.

The Windows-specific note is about a hard limit on the number of clipboard formats the system will hold, linked from the project documentation to a Microsoft blog post on the subject. The practical consequence is that an application that registers a format per data type, or per document, will eventually fail to register more, and the failure is a Windows limit rather than a bug in your code.

The macOS backend has no equivalent warning in the project notes, which is expected given that the pasteboard is organised around named types rather than a registry of format slots.

Taken together, the platform notes are the part of the documentation to read before designing a custom format, because they describe the three different ways a clipboard can refuse what you want to do with it.

Where clip is the wrong dependency

The first limitation is Linux. The library supports X11 and says so explicitly in its feature list, and there is no Wayland backend among the platform files. On a Linux system running Wayland, the X11 path either is unavailable or has to go through the XWayland compatibility layer, which is a different clipboard from the native one and does not always behave the same. For a distribution that ships Wayland by default, that makes clip a Windows and macOS library with a legacy Linux path, and that is a much weaker proposition than cross-platform.

The second is that the feature set is text, images and custom data. There is no file list, no rich text, no HTML flavour, no multiple selection handling. An editor that wants to put HTML on the clipboard alongside plain text has to register a custom format and do the conversion itself, which is precisely the work a more capable library would have done.

The third is the format enumeration gap. list_formats() is Windows only and behind a compile flag, so a cross-platform application that wants to show the user what is available on the clipboard cannot do it with clip. You would end up writing platform code anyway, which defeats the purpose.

The fourth is the governance of contributions. The project documentation states plainly that contributions using generative AI are not allowed, and the repository has a CONTRIBUTING.md alongside a build workflow badge and a tests directory. That is the maintainer's call to make, and it is worth knowing before you plan to contribute upstream rather than vendor the files, since it points a team toward maintaining its own copy.

Editorial conclusion

clip fits a desktop application that needs clipboard access, wants a single C++ API across Windows, macOS and X11, and would rather not take a widget toolkit as a dependency, since the API is small enough to read in one sitting and the MIT licence lets you vendor it. It is the wrong choice on a Wayland-only Linux desktop, where the library has no backend, and for a Windows application that needs to enumerate the clipboard formats, because that API exists only on Windows and behind a compile flag. Before adopting it, confirm your Linux target is X11 rather than Wayland, decide whether you need the image support and therefore the libpng dependency, and read the custom format advice about not storing platform-dependent types such as size_t, since the last push was on 2026-10-19 and the project ships no tagged releases.

Frequently asked questions

Official sources

1. dacap/clip on GitHub
2. Issues
3. License: MIT
4. README