custom-headless-tags

A headless-style Tags component built with React and Tailwind CSS v4.

Description

The Tags component is a customizable input for adding and removing tags. Users add tags by pressing Enter and remove them via the close control. Styling is done with Tailwind CSS classes you provide.

Peer dependencies: React and React DOM >=18.2.0.

Installation

npm install custom-headless-tags@latest

Local development / testing with npm link

To test the package locally before publishing:

1. In this package directory, build and link:

npm run rollup-build-lib
npm link

2. In your test project, link the package:

npm link custom-headless-tags

3. When finished testing, in your test project:

npm unlink custom-headless-tags
npm install

Usage

import React, { useState } from "react";
import { Tags } from "custom-headless-tags";

const App = () => {
  const [tags, setTags] = useState<string[]>([]);

  return (
    <div>
      <h1>Tag Input Example</h1>
      <Tags
        tags={tags}
        onTagAdd={(tag) => setTags([...tags, tag])}
        onTagDelete={(tagToDelete) => setTags(tags.filter((t) => t !== tagToDelete))}
        placeholder="Add an option..."
        className="focus:ring-olive-green ring-olive-green focus:ring-2 focus:ring-inset"
        tagClassName="text-sm rounded-b bg-timberwolf text-gray-600"
      />
    </div>
  );
};

export default App;

Props

| Prop | Type | Description | | -------------- | ------------------- | -------------------------------------------------------------------- | | tags | string[] | Array of tags to display. | | onTagAdd | (tag: string) => void | Called when a tag is added. | | onTagDelete | (tag: string) => void | Called when a tag is removed. | | placeholder | string | Input placeholder (default: "Add an option..."). | | label | React.ReactNode | Optional label for the field. | | className | string | Optional classes for the wrapper/input container. | | tagClassName | string | Optional classes for each tag (default includes bg-tag bg-opacity-50). | | disabled | boolean | Disables input and tag removal (default: false). |

Styles

The component uses Tailwind CSS utility classes. Your project must have Tailwind set up so those classes apply.

Tailwind v4

This package is built with Tailwind v4. In your app, use Tailwind v4 (e.g. @tailwindcss/postcss) and ensure your content paths include the package so its classes are included:

// postcss.config.js or similar
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

Include your main CSS that uses @import "tailwindcss" (or equivalent) so Tailwind base and utilities are available.

Customization

Pass className and tagClassName to match your design system. The component does not ship its own CSS file; all styling is via Tailwind classes.