defunkt/howl
1
0
Fork 1
Code Issues Pull Requests Activity
44cc1ac10f
howl/TAGS.md
Chris Wanstrath 0cad100197 ________ ______ _______ ______ ________ 
/        |/      \ /       \  /      \ /        |
$$$$$$$$//$$$$$$  |$$$$$$$  |/$$$$$$  |$$$$$$$$/
$$ |__   $$ |  $$ |$$ |__$$ |$$ | _$$/ $$ |__
$$    |  $$ |  $$ |$$    $$< $$ |/    |$$    |
$$$$$/   $$ |  $$ |$$$$$$$  |$$ |$$$$ |$$$$$/
$$ |     $$ \__$$ |$$ |  $$ |$$ \__$$ |$$ |_____
$$ |     $$    $$/ $$ |  $$ |$$    $$/ $$       |
$$/       $$$$$$/  $$/   $$/  $$$$$$/  $$$$$$$$/
2026-01-16 08:33:38 -08:00

14 KiB
Raw Blame History

HOWL Component Library - Complete Tags Reference

Built with Forge - a CSS-in-JS framework with theme support.

Quick Start

import { Styles, Button, VStack } from 'howl'

// Include <Styles /> in your document head to inject CSS
<html>
  <head>
    <Styles />
  </head>
  <body data-theme="light">
    <VStack gap={4}>
      <Button>Click Me</Button>
    </VStack>
  </body>
</html>

Theming

Howl includes light and dark themes. Set data-theme="light" or data-theme="dark" on your root element.

Customizing the Theme

import { extendThemes } from 'howl'

extendThemes({
  light: { 'colors-primary': '#8b5cf6' },
  dark: { 'colors-primary': '#a78bfa' }
})

Table of Contents

Layout Components

VStack

Vertical stack layout component using flexbox or CSS Grid for flexible vertical layouts.

Props:

  • v?: "start" | "center" | "end" | "between" | "around" | "evenly" - Main axis alignment (vertical)
  • h?: "start" | "center" | "end" | "stretch" | "baseline" - Cross axis alignment (horizontal)
  • gap?: 0 | 1 | 2 | 3 | 4 | 6 | 8 | 12 - Gap between items (multiplied by 4px)
  • rows?: number[] - Custom row sizing fractions (e.g., [2, 1] for 2/3 and 1/3 height)
  • wrap?: boolean - Enable flex-wrap
  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref
  • children?: any - Child elements

Examples:

<VStack>Content</VStack>
<VStack gap={4} v="center">Content</VStack>
<VStack rows={[2, 1]}>Content</VStack>

HStack

Horizontal stack layout component using flexbox or CSS Grid for flexible horizontal layouts.

Props:

  • h?: "start" | "center" | "end" | "between" | "around" | "evenly" - Main axis alignment (horizontal)
  • v?: "start" | "center" | "end" | "stretch" | "baseline" - Cross axis alignment (vertical)
  • gap?: 0 | 1 | 2 | 3 | 4 | 6 | 8 | 12 - Gap between items (multiplied by 4px)
  • cols?: number[] - Custom column sizing fractions (e.g., [7, 3] for 70% and 30% width)
  • wrap?: boolean - Enable flex-wrap
  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref
  • children?: any - Child elements

Examples:

<HStack>Content</HStack>
<HStack gap={6} h="between" v="center">Content</HStack>
<HStack cols={[7, 3]} gap={4}>Content</HStack>

Grid

CSS Grid component for creating multi-column layouts.

Props:

  • cols?: 1 | 2 | 3 | 4 | 5 | 6 | 7 - Number of columns. Default: 2
  • gap?: 0 | 1 | 2 | 3 | 4 | 6 | 8 | 12 - Gap between items (multiplied by 4px). Default: 4
  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref
  • children?: any - Child elements

Examples:

<Grid cols={3}>Items</Grid>
<Grid cols={4} gap={6}>Items</Grid>

Section

Wrapper component that adds padding and vertical stacking with gap control.

Props:

  • gap?: 0 | 1 | 2 | 3 | 4 | 6 | 8 | 12 - Gap between children (multiplied by 4px). Default: 8
  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref
  • children?: any - Child elements

Examples:

<Section>Content</Section>
<Section gap={4}>Content</Section>

Container Components

Box

Generic container component. Use color variants for common patterns.

Variants:

  • Box - Plain container (no default styles)
  • RedBox - Red background, white text, 4px padding
  • GreenBox - Green background, white text, 4px padding
  • BlueBox - Blue background, white text, 4px padding
  • GrayBox - Gray background, 16px padding

Props:

  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref
  • children?: any - Child elements

Examples:

<Box>Content</Box>
<RedBox>Red content</RedBox>
<BlueBox>Blue content</BlueBox>

Typography Components

H1, H2, H3, H4, H5

Heading components with preset font sizes and weights.

Props (all heading components):

  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref
  • children?: any - Child elements

Sizing:

  • H1 - 24px, bold
  • H2 - 20px, bold
  • H3 - 18px, semibold (600)
  • H4 - 16px, semibold (600)
  • H5 - 14px, medium (500)

Examples:

<H1>Heading 1</H1>
<H2>Heading 2</H2>
<H3>Heading 3</H3>

Text

Standard paragraph text component.

Props:

  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref
  • children?: any - Child elements

Sizing: 14px

Examples:

<Text>Regular text</Text>

SmallText

Small paragraph text component.

Props: Same as Text

Sizing: 12px

Examples:

<SmallText>Small text</SmallText>

Interactive Components

Button

Clickable button component with multiple variants and sizes.

Props (extends HTML button attributes):

  • variant?: "primary" | "secondary" | "outline" | "ghost" | "destructive" - Button style. Default: "primary"
  • size?: "sm" | "md" | "lg" - Button size. Default: "md"
  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref
  • Plus all native button attributes (onClick, disabled, type, etc.)

Variants:

  • primary - Primary color background, white text
  • secondary - Secondary color background, white text
  • outline - Transparent background, border
  • ghost - Transparent background, no border
  • destructive - Destructive color background, white text

Sizes:

  • sm - 32px height
  • md - 40px height
  • lg - 48px height

Examples:

<Button>Click Me</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline" size="lg">Large</Button>
<Button onClick={handleClick}>Action</Button>
<Button disabled>Disabled</Button>

Input

Text input component with optional label positioning.

Props (extends HTML input attributes):

  • labelPosition?: "above" | "left" | "right" - Label position relative to input. Default: "above"
  • children?: any - Label text (passed as children)
  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref
  • Plus all native input attributes (type, placeholder, value, disabled, etc.)

Examples:

<Input placeholder="Enter name" />
<Input type="email" placeholder="Email" />
<Input>Label</Input>
<Input labelPosition="left">Name</Input>
<Input labelPosition="right">Label</Input>

Select

Dropdown select component with optional label positioning.

Props:

  • options: SelectOption[] - Array of options (required). SelectOption = { value: string, label: string, disabled?: boolean }
  • placeholder?: string - Placeholder text
  • labelPosition?: "above" | "left" | "right" - Label position relative to select. Default: "above"
  • children?: any - Label text (passed as children)
  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref
  • Plus all native select attributes (value, onChange, disabled, etc.)

Examples:

<Select options={options} />
<Select options={options} placeholder="Choose" />
<Select options={options}>Label</Select>
<Select options={options} labelPosition="left">Label</Select>

Media Components

Image

Image component with object-fit support.

Props:

  • src: string - Image URL (required)
  • alt?: string - Alt text for accessibility
  • width?: number - Width in pixels
  • height?: number - Height in pixels
  • objectFit?: "cover" | "contain" | "fill" | "none" | "scale-down" - CSS object-fit property
  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref

Examples:

<Image src="/photo.jpg" />
<Image src="/photo.jpg" width={200} height={200} />
<Image src="/photo.jpg" objectFit="cover" />

Avatar

Avatar image component with size and rounded variants.

Props:

  • src: string - Image URL (required)
  • alt?: string - Alt text for accessibility
  • size?: 24 | 32 | 48 | 64 | 96 | 128 - Avatar size in pixels. Default: 32
  • rounded?: boolean - Make avatar circular
  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref

Examples:

<Avatar src="/user.jpg" />
<Avatar src="/user.jpg" size={64} />
<Avatar src="/user.jpg" size={48} rounded />

Icon

Icon component using Lucide static SVG icons.

Props:

  • name: IconName - Icon name from Lucide (required). Available: Heart, Star, Home, ExternalLink, Mail, Phone, Download, Settings, Shield, Sun, Zap, and many more
  • size?: 4 | 5 | 6 | 8 | 10 | 12 - Icon size in Tailwind units (multiplied by 4px). Default: 6 (24px)
  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref

Examples:

<Icon name="Heart" />
<Icon name="Star" size={8} />
<Icon name="Home" style={{ color: "#3b82f6" }} />

IconLink

Icon wrapped in an anchor link.

Props (extends Icon props):

  • All Icon props plus:
  • href?: string - Link URL. Default: "#"
  • target?: string - Link target (e.g., "_blank")

Examples:

<IconLink name="ExternalLink" href="/link" />
<IconLink name="Home" href="/" />
<IconLink name="ExternalLink" href="https://example.com" target="_blank" />

Utility Components

Divider

Horizontal divider line with optional text.

Props:

  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref
  • children?: any - Text to display on the line

Examples:

<Divider />
<Divider>OR</Divider>

Placeholder

Object containing placeholder generator utilities for Avatar and Image components.

Placeholder.Avatar

Generates placeholder avatars using DiceBear API.

Props:

  • seed?: string - Seed for consistent avatar generation. Default: "seed"
  • type?: DicebearStyleName - Avatar style. Default: "dylan"
  • size?: number - Avatar size in pixels. Default: 32
  • transparent?: boolean - Use transparent background
  • rounded?: boolean - Make circular
  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref
  • alt?: string - Alt text

Available DiceBear Styles: adventurer, adventurer-neutral, avataaars, avataaars-neutral, big-ears, big-ears-neutral, big-smile, bottts, bottts-neutral, croodles, croodles-neutral, dylan, fun-emoji, glass, icons, identicon, initials, lorelei, lorelei-neutral, micah, miniavs, notionists, notionists-neutral, open-peeps, personas, pixel-art, pixel-art-neutral, rings, shapes, thumbs

Examples:

<Placeholder.Avatar />
<Placeholder.Avatar type="avataaars" size={64} />
<Placeholder.Avatar seed="alice" rounded />

Placeholder.Image

Generates placeholder images using Picsum Photos API.

Props:

  • width?: number - Image width in pixels. Default: 200
  • height?: number - Image height in pixels. Default: 200
  • seed?: number - Seed for consistent image generation. Default: 1
  • alt?: string - Alt text. Default: "Placeholder image"
  • objectFit?: "cover" | "contain" | "fill" | "none" | "scale-down" - CSS object-fit
  • class?: string - CSS class name
  • style?: JSX.CSSProperties - Inline styles
  • id?: string - HTML id attribute
  • ref?: any - React ref

Examples:

<Placeholder.Image />
<Placeholder.Image width={200} height={200} />
<Placeholder.Image seed={42} />

Type Definitions

SelectOption

Type for Select component options:

{
  value: string      // Option value
  label: string      // Display text
  disabled?: boolean // Disable option
}

Export Summary

import {
  // Utilities
  Styles,           // CSS injection component - include in <head>
  theme,            // Theme function for accessing CSS variables
  extendThemes,     // Override theme values globally
  cn,               // Class name helper

  // Layout
  VStack, HStack, Grid, Section,

  // Container
  Box, RedBox, GreenBox, BlueBox, GrayBox,

  // Typography
  H1, H2, H3, H4, H5, Text, SmallText,

  // Interactive
  Button, Input, Select,

  // Media
  Image, Avatar, Icon, IconLink,

  // Utility
  Divider, Placeholder,

  // Types
  type ButtonProps,
  type ImageProps,
  type AvatarProps,
  type InputProps,
  type SelectProps,
  type SelectOption,
  type IconName,
} from 'howl'