Using Third-party Libraries

Third-party CSS

The ergonomics for this aren't ideal, and I plan on making tooling to make this experiense better.

If you're using third-party CSS such as Bootstrap or Tailwind, you'll need to move the CSS over to a *.pc file. For example:

.my-1 {
/* tailwind code */
}
.my-2 {
/* tailwind code */
}
.text-color-black-100 {
/* tailwind code */
}

This must be converted to Paperclip like so:

<style>
@export {
.my-1 {
/* tailwind code */
}
.my-2 {
/* tailwind code */
}
.text-color-black-100 {
/* tailwind code */
}
}
</style>

The @export block is necessary for CSS that you plan on using in other Paperclip files, since Paperclip requires explicity. You can make all selectors global with :global if you really want to, but I don't recommend that because you're losing safety in favor of convenience.

☝ Here's how you can use these styles in another Paperclip file:

<import src="modules/tailwind.pc" as="tw" />
<div className="$tw.text-color-black-100 $tw.my-1">
Something
</div>

The Tailwind example is a good place to start if you're looking to do this.

Styling third-party components

You may use classes defined in Paperclip on third-party components. Here's a simple example:

<style>
@export {
.my-styles {
/* some components may have nested style rules in the global namespace.
In that case you can use the :global selector */
:global(.nested-rule) {
}
}
}
</style>

Then, in your JSX code:

import * as ui from "./Component.pc";
import SomeThirdPartyComponent from "some-third-paty-component";
<SomeThirdPartyComponent className={ui.classNames["my-style"]} />

☝ this works for many cases. However, it's a bit inconvenient since you'll be using the browser in order to debug your styles. To make things easier, you can copy & paste the third-party component's HTML & CSS directly in your PC file & open it up in VS Code to visually style it. Don't worry, this approach is only a guide to make custom styling easier. It's not for production.

alt copy-paste html

Let's use a real example now. Here's a custom theme for the react select module:

Select.pc
tokens.pc
⚡️ Preview

Here's how we can apply this theme in React code:

import { Wrapper as SelectWrapper } from './Select.pc';
import Select from 'react-select';
function StyledSelect(props) {
return (
<SelectWrapper>
<Select classNamePrefix="select" {...props} />
</SelectWrapper>
);
}

That's all there is to it really.