A TypeScript utility library for tri-state checkbox functionality in Angular applications
npm install primeng-tri-state-checkboxA TypeScript utility library for tri-state checkbox functionality in Angular applications, specifically designed for PrimeNG 19+ and optimized for Tailwind CSS.
- 🔄 Tri-state cycling: null → true → false → null
- 🎨 PrimeNG integration: Built specifically for PrimeNG p-checkbox component
- 🎯 TypeScript support: Full type safety and IntelliSense
- 🎨 Tailwind CSS utilities: Pre-built classes for visual feedback
- 📦 Tree-shakeable: Import only what you need
- 🚀 Zero dependencies: Lightweight and fast
``bash`
npm install primeng-tri-state-checkbox
`bash`
npm install @angular/forms primeng
`typescript
import { turnToTriState } from 'primeng-tri-state-checkbox';
import { FormControl } from '@angular/forms';
// Create a form control with tri-state value
const formControl = new FormControl
// Use with form control directly - it will cycle the control's value
turnToTriState(formControl); // null → true → false → null
// Or use with direct values - it returns the next state
let currentValue: boolean | null = null;
currentValue = turnToTriState(currentValue); // returns true
currentValue = turnToTriState(currentValue); // returns false
currentValue = turnToTriState(currentValue); // returns null
`
`typescript
import {
turnToTriState,
cycleTriState,
getPrimeNGTriStateProps
} from 'primeng-tri-state-checkbox';
// If you need more specific control, you can still use individual functions
const nextValue = cycleTriState(currentValue);
const primeNGProps = getPrimeNGTriStateProps(currentValue);
`
`typescript
import { Component } from '@angular/core';
import { FormBuilder, FormGroup } from '@angular/forms';
import { turnToTriState } from 'primeng-tri-state-checkbox';
@Component({
selector: 'app-example',
template:
})
export class ExampleComponent {
form: FormGroup; constructor(private fb: FormBuilder) {
this.form = this.fb.group({
hasFusing: [null] // Start with indeterminate state
});
}
// Make turnToTriState available in template
turnToTriState = turnToTriState;
}
API Reference
$3
####
Cycles through tri-state values: null → true → false → null####
Cycles a FormControl through tri-state values$3
####
Returns props object for PrimeNG p-checkbox:
typescript
{
value: boolean | null;
indeterminate: boolean;
binary: boolean;
}
`####
Event handler for PrimeNG onChange events####
Generates complete HTML template for PrimeNG tri-state checkbox$3
####
Returns Tailwind CSS classes for visual feedback:
- : yellow theme (unknown/indeterminate)
- true: green theme (positive)
- false: red theme (negative)####
getTriStateIcon(value: boolean | null, iconSet?: 'pi' | 'fa'): string
Returns icon classes for tri-state representation:
- : minus icon
- true: check icon
- false: times/x icon$3
####
triStateToString(value: boolean | null): 'true' | 'false' | 'null'
Converts tri-state value to string####
Parses string to tri-state value####
Returns human-readable labels for each stateAdvanced Examples
$3
typescript
import { getTriStateTailwindClasses, getTriStateIcon } from 'primeng-tri-state-checkbox';@Component({
template:
})
export class CustomStyledComponent {
getStateClasses(value: boolean | null): string {
return getTriStateTailwindClasses(value, {
null: 'bg-gray-100 border-gray-300 text-gray-700',
true: 'bg-emerald-50 border-emerald-300 text-emerald-700',
false: 'bg-rose-50 border-rose-300 text-rose-700'
});
} getStateIcon(value: boolean | null): string {
return getTriStateIcon(value, 'pi');
}
}
$3
typescript
@Component({
template:
})
export class MultiTriStateComponent {
triStateFields = [
{ key: 'hasWarranty', label: 'Has Warranty?' },
{ key: 'isActive', label: 'Is Active?' },
{ key: 'isVerified', label: 'Is Verified?' }
]; form = this.fb.group({
hasWarranty: [null],
isActive: [null],
isVerified: [null]
});
turnToTriState = turnToTriState;
getTriStateTailwindClasses = getTriStateTailwindClasses;
getTriStateLabel = getTriStateLabel;
}
TypeScript Types
typescript
interface TriStateFormControl {
value: boolean | null;
setValue(value: boolean | null): void;
}type TriStateValue = boolean | null;
type TriStateString = 'true' | 'false' | 'null';
`Development & Contributing
$3
This package uses automated versioning and publishing through GitHub Actions. Contributors don't need to manually update versions or publish to NPM.
#### Commit Message Format
Use conventional commit messages to trigger automatic version bumps:
bash
For bug fixes (patch version: 1.0.0 → 1.0.1)
git commit -m "fix: resolve checkbox state issue"For new features (minor version: 1.0.0 → 1.1.0)
git commit -m "feat: add new utility function"For breaking changes (major version: 1.0.0 → 2.0.0)
git commit -m "major: change API interface"
OR
git commit -m "feat: new featureBREAKING CHANGE: API has changed"
Other commits (no version bump)
git commit -m "docs: update README"
git commit -m "chore: update dependencies"
`#### Development Workflow
1. Make your changes
2. Commit with proper message format
3. Push to main branch
4. GitHub Actions automatically:
- Runs tests and type checking
- Bumps version based on commit message
- Publishes to NPM
- Creates git tags
bash
Example workflow
git add .
git commit -m "feat: add new tri-state utility"
git push origin main
🎉 Package automatically published!
`#### Pull Request Workflow
For larger changes, use pull requests:
bash
Create feature branch
git checkout -b feature/new-functionalityMake changes and commit
git commit -m "feat: add advanced tri-state features"Push and create PR
git push origin feature/new-functionality
Create PR on GitHub → Merge → Automatic publish!
``- Modern browsers supporting ES2020+
- Angular 19+
- PrimeNG 19+
Contributions are welcome! Please feel free to submit a Pull Request.
MIT License. See LICENSE file for details.
- PrimeNG Documentation
- Tailwind CSS
- Angular Reactive Forms