Chip

Overview

The Chip is a small status indicator element positioned at the corner of another element, commonly used for notification badges, unread counts, and online status dots. It is composed of two recipe parts: useChipRecipe() for the positioning wrapper and useChipIndicatorRecipe() for the indicator itself. Each composable creates a fully configured recipe with color, variant, size, position, and inset options — plus compound variants that handle the color-variant combinations automatically.

The Chip recipes integrate directly with the default design tokens preset and generate type-safe utility classes at build time with zero runtime CSS.

Why use the Chip recipe?

The Chip recipe helps you:

• Ship faster with sensible defaults: Get 9 colors, 2 visual styles, 5 sizes, 4 positions, and an inset mode out of the box with two composable calls.
• Compose structured layouts: Two coordinated recipes (wrapper and indicator) work together so the indicator is always positioned correctly relative to the wrapped element.
• Maintain consistency: Compound variants ensure every color-variant combination follows the same design rules, including dark mode overrides.
• Customize without forking: Override base styles, default variants, or filter out options you don't need — all through the options API.
• Stay type-safe: Full TypeScript support means your editor catches invalid color, variant, size, or position values at compile time.
• Integrate with your tokens: Every value references the design tokens preset, so theme changes propagate automatically.
• Support dark mode: Background and text colors adapt automatically between light and dark color schemes.

Usage

import { styleframe } from 'virtual:styleframe';
import { useChipRecipe, useChipIndicatorRecipe } from '@styleframe/theme';

const s = styleframe();

const chip = useChipRecipe(s);
const chipIndicator = useChipIndicatorRecipe(s);

export default s;

import { chip, chipIndicator } from "virtual:styleframe";

interface ChipProps {
    color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "light" | "dark" | "neutral";
    variant?: "solid" | "soft";
    size?: "xs" | "sm" | "md" | "lg" | "xl";
    position?: "top-right" | "top-left" | "bottom-right" | "bottom-left";
    inset?: boolean;
    text?: string;
    children?: React.ReactNode;
}

export function Chip({
    color = "primary",
    variant = "solid",
    size = "md",
    position = "top-right",
    inset = false,
    text,
    children,
}: ChipProps) {
    return (
        <div className={chip()}>
            {children}
            <span
                className={chipIndicator({
                    color,
                    variant,
                    size,
                    position,
                    inset: String(inset),
                })}
            >
                {text}
            </span>
        </div>
    );
}

<script setup lang="ts">
import { chip, chipIndicator } from "virtual:styleframe";

const props = withDefaults(
    defineProps<{
        color?: "primary" | "secondary" | "success" | "info" | "warning" | "error" | "light" | "dark" | "neutral";
        variant?: "solid" | "soft";
        size?: "xs" | "sm" | "md" | "lg" | "xl";
        position?: "top-right" | "top-left" | "bottom-right" | "bottom-left";
        inset?: boolean;
        text?: string;
    }>(),
    { color: "primary", variant: "solid", size: "md", position: "top-right", inset: false },
);
</script>

<template>
    <div :class="chip()">
        <slot />
        <span
            :class="chipIndicator({
                color,
                variant,
                size,
                position,
                inset: inset ? 'true' : 'false',
            })"
        >
            {{ text }}
        </span>
    </div>
</template>

Colors

The Chip indicator recipe includes 9 color variants: 6 semantic colors (primary, secondary, success, info, warning, error) plus 3 neutral-scale colors (light, dark, neutral). Each color is combined with every visual style variant through compound variants, so you get consistent, predictable styling across all combinations — including dark mode overrides.

Color Reference

Variants

Two visual style variants control how the indicator is rendered. Each variant is combined with the selected color through compound variants, so you always get the correct background and text colors for your chosen color.

Solid

Filled background with light text. The most prominent style, ideal for notification counts and status indicators that need high visibility.

Soft

Light tinted background with colored text. A subtler style that works well for secondary indicators and badges that shouldn't dominate the visual hierarchy. In dark mode, the tint and text colors automatically adjust.

Sizes

Five size variants from xs to xl control the dimensions, font size, and padding of the indicator. The xs size produces a small dot with no text, while larger sizes accommodate text content.

Size Reference

Position

The position variant controls which corner of the parent element the indicator is placed at. The indicator is absolutely positioned and uses CSS transform to offset itself to straddle the corner.

Inset

The inset variant controls whether the indicator overlaps the corner of the parent element or sits inside it. When inset is true, the transform offset is removed so the indicator stays within the parent's bounds.

With Text

Chip indicators can display text content such as notification counts. Sizes sm through xl include horizontal padding and min-width to accommodate text while maintaining a pill shape thanks to the full border radius.

Anatomy

The Chip recipe is composed of two independent recipes that work together:

The wrapper provides the positioning context. The indicator is a child element that positions itself at one of the four corners using absolute positioning and transforms.

<!-- Both parts working together -->
<div class="chip()">
    <img src="avatar.png" alt="User avatar" />
    <span class="chipIndicator({ color: 'success', size: 'xs' })"></span>
</div>

Accessibility

• Use semantic HTML. Use a <span> for the indicator element. It is a visual decoration that augments the wrapped element.

<!-- Correct: indicator as a span -->
<div class="chip()">
    <button>Notifications</button>
    <span class="chipIndicator(...)">5</span>
</div>

• Add aria-label for screen readers. The indicator's text content alone may not provide enough context. Add an aria-label to the wrapped element or use aria-describedby to associate the count with the action.

<div class="chip()">
    <button aria-label="Notifications, 5 unread">Notifications</button>
    <span class="chipIndicator(...)" aria-hidden="true">5</span>
</div>

• Hide decorative indicators. When the indicator is a status dot without text (e.g., xs size), add aria-hidden="true" to prevent screen readers from announcing an empty element.

<!-- Status dot: hidden from screen readers -->
<div class="chip()">
    <img src="avatar.png" alt="User avatar, online" />
    <span class="chipIndicator({ size: 'xs', color: 'success' })" aria-hidden="true"></span>
</div>

Customization

Overriding Defaults

Each chip composable accepts an optional second argument to override any part of the recipe configuration. Overrides are deep-merged with the defaults, so you only need to specify the properties you want to change:

import { styleframe } from 'virtual:styleframe';
import { useChipRecipe, useChipIndicatorRecipe } from '@styleframe/theme';

const s = styleframe();

const chip = useChipRecipe(s);
const chipIndicator = useChipIndicatorRecipe(s, {
    defaultVariants: {
        color: 'success',
        variant: 'solid',
        size: 'xs',
        position: 'bottom-right',
        inset: 'false',
    },
});

export default s;

Filtering Variants

If you only need a subset of the available variants, use the filter option to limit which values are generated. This reduces the output CSS and keeps your component API focused:

import { styleframe } from 'virtual:styleframe';
import { useChipRecipe, useChipIndicatorRecipe } from '@styleframe/theme';

const s = styleframe();

// Only generate primary and error colors, with solid style
const chip = useChipRecipe(s);
const chipIndicator = useChipIndicatorRecipe(s, {
    filter: {
        color: ['primary', 'error'],
        variant: ['solid'],
    },
});

export default s;

API Reference

useChipRecipe(s, options?)

Creates the chip wrapper recipe that establishes the positioning context for the indicator.

Parameters:

The wrapper recipe has no variants. It sets position: relative and display: inline-flex as base styles.

useChipIndicatorRecipe(s, options?)

Creates the chip indicator recipe with color, variant, size, position, and inset support.

Parameters:

Variants:

Learn more about recipes →

Best Practices

• Choose colors by meaning, not appearance: Use success for online status and error for alert counts — this keeps your UI consistent when tokens change.
• Use xs for status dots: The smallest size creates a perfect circle without text, ideal for online/offline indicators.
• Use solid for high-visibility badges: Solid indicators stand out against most backgrounds. Use soft for subtler, less urgent indicators.
• Match position to reading direction: top-right (default) works well for LTR layouts. Consider top-left for RTL layouts.
• Use inset for tight layouts: When the indicator shouldn't overflow the parent's bounds, enable inset mode to keep it inside the corner.
• Filter what you don't need: If your component only uses a few colors or sizes, pass a filter option to reduce generated CSS.
• Override defaults at the recipe level: Set your most common variant combination as defaultVariants so component consumers write less code.

FAQ