# Bestax-Bulma

> A Bulma React component library. LLM-friendly documentation for @allxsmith/bestax-bulma.

This file contains all documentation content in a single document following the llmstxt.org standard.

## Quick Start


## Create a Bestax App

The fastest way to get started. The scaffolder sets up a Vite + React project with bestax-bulma and CSS pre-configured:

```bash
pnpm create bestax@latest my-bestax-app
cd my-bestax-app
pnpm install
pnpm dev
```

:::info CSS is included automatically
The scaffolder configures `bestax.css` for you — a single stylesheet that includes both Bulma and all bestax extras. No manual CSS setup needed.
:::

That's it! Visit http://localhost:5173 to see your app. Skip ahead to [Next Steps](#next-steps), or keep reading to add bestax to an existing project.

---

## Add to an Existing Project

### Install Dependencies

```bash
pnpm add @allxsmith/bestax-bulma
```

### Add Bestax CSS

Import the combined stylesheet in your application entry point (e.g. `main.jsx`, `main.tsx`, `index.js`):

```js

```

This single import includes both Bulma base styles and all bestax extras.

:::tip Already using Bulma?
If you already import Bulma CSS separately, you can keep that and just add the extras:

```js

```

:::

---

## Use Your First Component

Replace `src/App.jsx` (or add to your existing app):

```jsx title="src/App.jsx"

function App() {
  const [showAlert, setShowAlert] = useState(false);

  return (
    <Box>
      <Title>Welcome to bestax-bulma!</Title>

      <Button color="primary" onClick={() => setShowAlert(!showAlert)}>
        Click me!
      </Button>

      {showAlert && (
        <Notification color="success" mt="4">
          Great! You're ready to build with bestax-bulma.
        </Notification>
      )}
    </Box>
  );
}

export default App;
```

---

## Run Your App

```bash
pnpm dev
```

Visit http://localhost:5173 to see your app running.

---

## Next Steps

- [Installation Options](/docs/guides/getting-started/installation) -- Icon libraries, CDN, custom Bulma builds, and more
- [Extra Components](/docs/guides/library/components) -- Toast, Dialog, Slider, Switch, and other extras
- [Toolchains](/docs/guides/getting-started/react-setups) -- Next.js, TypeScript, and Create React App guides
- [Browse Components](/docs/category/elements) -- Full API docs and live examples

---

## Custom Component

# Custom Component skill

The [`bestax-custom-component`](https://github.com/allxsmith/bestax/blob/main/skills/bestax-custom-component/SKILL.md)
skill teaches an agent to build a new custom component the bestax way — starting by
**checking whether a matching component already exists**, then the helper hooks and the Bulma v1
SCSS pattern, plus stories, tests, and docs.

## Install

```bash
npx skills add https://github.com/allxsmith/bestax --skill bestax-custom-component
```

## Example

An agent was asked to build a `ProfileCard` and followed the skill.

<ExampleMeta
  skill="bestax-custom-component"
  skillHref="https://github.com/allxsmith/bestax/blob/main/skills/bestax-custom-component/SKILL.md"
  model="Claude Opus 4.8"
  date="2026-06-27"
/>

### Prompt

```text
Build a ProfileCard component — avatar on top, then name, role, and a short
description — following the bestax custom-component skill.
```

:::info What the skill checked first
There is no `ProfileCard` in the library — but `Card`, `Image`, `Title`, `SubTitle`, and
`Content` already exist. So rather than reinventing them, `ProfileCard` is a new component that
**composes** the existing elements and adds only its own layout. (Had the request been a "label"
or "badge", the skill would have stopped and pointed at the existing `Tag` / `Tags`.)
:::

### Live result

```tsx live
function example() {
  return (
    
      <ProfileCard
        name="Ada Lovelace"
        role="Mathematician & Writer"
        imageSrc="https://upload.wikimedia.org/wikipedia/commons/thumb/a/a4/Ada_Lovelace_portrait.jpg/330px-Ada_Lovelace_portrait.jpg"
      >
        English mathematician who worked on Charles Babbage's proposed
        Analytical Engine. She was the first to recognise that the machine had
        applications beyond pure calculation, and published what is now regarded
        as the first algorithm intended to be carried out by a machine.
      </ProfileCard>
      <ProfileCard
        name="Alan Turing"
        role="Computer Scientist"
        imageSrc="https://upload.wikimedia.org/wikipedia/commons/thumb/a/a1/Alan_Turing_Aged_16.jpg/330px-Alan_Turing_Aged_16.jpg"
      >
        British mathematician and logician who formalised the concepts of
        algorithm and computation with the Turing machine. His wartime
        codebreaking at Bletchley Park helped shorten the Second World War, and
        he is widely considered the father of theoretical computer science.
      </ProfileCard>
    
  );
}
```

### Generated code

<Tabs>
<TabItem value="component" label="ProfileCard.tsx">

```tsx

// Compose the existing elements rather than reinventing them.

export interface ProfileCardProps
  extends
    Omit<React.HTMLAttributes<HTMLDivElement>, 'title' | 'color'>,
    BulmaClassesProps {
  name: string;
  role?: string;
  imageSrc: string;
  imageAlt?: string;
}

export const ProfileCard = forwardRef<HTMLDivElement, ProfileCardProps>(
  ({ name, role, imageSrc, imageAlt, className, children, ...props }, ref) => {
    const { bulmaHelperClasses, rest } = useBulmaClasses(props);
    const cardClass = usePrefixedClassNames('profile-card');
    const imageClass = usePrefixedClassNames('profile-card-image');
    const bodyClass = usePrefixedClassNames('profile-card-body');
    const combined = classNames(cardClass, bulmaHelperClasses, className);

    return (
      
        
          <Image
            size="128x128"
            src={imageSrc}
            alt={imageAlt ?? name}
            isRounded
          />
        
        
          <Title size="4" as="h3">
            {name}
          </Title>
          {role && (
            <SubTitle size="6" as="p">
              {role}
            </SubTitle>
          )}
          {children && <Content>{children}</Content>}
        
      
    );
  }
);

ProfileCard.displayName = 'ProfileCard';

export default ProfileCard;
```

</TabItem>
<TabItem value="scss" label="_profilecard.scss">

```scss
@use 'bulma/sass/utilities/initial-variables' as iv;
@use 'bulma/sass/utilities/css-variables' as cv;

$profile-card-width: 20rem !default;
$profile-card-min-height: 26rem !default;
$profile-card-avatar-size: 9rem !default;
$profile-card-background: cv.getVar('scheme-main') !default;
$profile-card-border: cv.getVar('border-weak') !default;
$profile-card-radius: cv.getVar('radius-large') !default;
$profile-card-shadow: 0 0.5em 1em -0.125em hsla(0, 0%, 4%, 0.1) !default;
$profile-card-padding: 1.5rem !default;
$profile-card-gap: 0.75rem !default;

.#{iv.$class-prefix}profile-card {
  @include cv.register-vars(
    (
      'profile-card-width': #{$profile-card-width},
      'profile-card-min-height': #{$profile-card-min-height},
      'profile-card-avatar-size': #{$profile-card-avatar-size},
      'profile-card-background': #{$profile-card-background},
      'profile-card-border': #{$profile-card-border},
      'profile-card-radius': #{$profile-card-radius},
      'profile-card-shadow': #{$profile-card-shadow},
      'profile-card-padding': #{$profile-card-padding},
      'profile-card-gap': #{$profile-card-gap},
    )
  );
}

.#{iv.$class-prefix}profile-card {
  display: flex;
  flex-direction: column;
  align-items: center; // horizontal centering of the column
  text-align: center;
  width: cv.getVar('profile-card-width');
  min-height: cv.getVar('profile-card-min-height');
  max-width: 100%;
  gap: cv.getVar('profile-card-gap');
  padding: cv.getVar('profile-card-padding');
  background-color: cv.getVar('profile-card-background');
  border: 1px solid cv.getVar('profile-card-border');
  border-radius: cv.getVar('profile-card-radius');
  box-shadow: cv.getVar('profile-card-shadow');
}

.#{iv.$class-prefix}profile-card-image {
  display: flex;
  justify-content: center;
}

// Enlarge the composed avatar and crop (not stretch) the portrait to a circle.
.#{iv.$class-prefix}profile-card-image .#{iv.$class-prefix}image {
  width: cv.getVar('profile-card-avatar-size');
  height: cv.getVar('profile-card-avatar-size');
}
.#{iv.$class-prefix}profile-card-image .#{iv.$class-prefix}image img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}

.#{iv.$class-prefix}profile-card-body {
  display: flex;
  flex-direction: column;
  gap: 0.25rem;
}
```

</TabItem>
<TabItem value="usage" label="Usage">

```tsx

<ProfileCard name="Ada Lovelace" role="Mathematician" imageSrc="/ada.jpg">
  Wrote the first algorithm intended to be carried out by a machine.
</ProfileCard>;
```

</TabItem>
</Tabs>

:::note
`ProfileCard` is an **example** produced by the skill — it is not part of the published
`@allxsmith/bestax-bulma` package. The point is the _pattern_ (check first, compose existing
elements, follow the SCSS convention, then **inspect it in a browser** to confirm spacing and
alignment). See the full skill on
[GitHub](https://github.com/allxsmith/bestax/tree/main/skills/bestax-custom-component).
:::

---

## Form

# Form skill

The [`bestax-form`](https://github.com/allxsmith/bestax/blob/main/skills/bestax-form/SKILL.md)
skill teaches an agent to build forms with the bestax form components. There is **no form
library** — state is plain React, and errors surface via `color="danger"` + `message` +
`messageColor`.

## Install

```bash
npx skills add https://github.com/allxsmith/bestax --skill bestax-form
```

## Signup & validation

<ExampleMeta
  skill="bestax-form"
  skillHref="https://github.com/allxsmith/bestax/blob/main/skills/bestax-form/SKILL.md"
  model="Claude Opus 4.8"
  date="2026-06-27"
/>

### Prompt

```text
Build a signup form (name, email, country) that validates on submit and shows
inline errors — no form library — following the bestax form skill.
```

### Live form

Click **Create account** with empty fields to see the validation.

```tsx live
function example() {
  const [name, setName] = useState('');
  const [email, setEmail] = useState('');
  const [country, setCountry] = useState('');
  const [submitted, setSubmitted] = useState(false);

  const errors = {
    name: !name.trim() ? 'Name is required.' : undefined,
    email: !/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(email)
      ? 'Enter a valid email.'
      : undefined,
    country: !country ? 'Pick a country.' : undefined,
  };
  const show = k => (submitted ? errors[k] : undefined);

  return (
    <form
      onSubmit={e => {
        e.preventDefault();
        setSubmitted(true);
      }}
      style={{ maxWidth: '28rem' }}
    >
      <Input
        label="Name"
        value={name}
        onChange={e => setName(e.target.value)}
        color={show('name') ? 'danger' : undefined}
        message={show('name')}
        messageColor="danger"
        iconLeftName="user"
      />
      <Input
        label="Email"
        type="email"
        value={email}
        onChange={e => setEmail(e.target.value)}
        color={show('email') ? 'danger' : undefined}
        message={show('email')}
        messageColor="danger"
        iconLeftName="envelope"
      />
      <Select
        label="Country"
        value={country}
        onChange={e => setCountry(e.target.value)}
        color={show('country') ? 'danger' : undefined}
        message={show('country')}
        messageColor="danger"
      >
        <option value="">Select…</option>
        <option value="us">United States</option>
        <option value="ca">Canada</option>
        <option value="uk">United Kingdom</option>
      </Select>
      <Button color="primary" type="submit">
        Create account
      </Button>
    </form>
  );
}
```

### Validation pattern

Own the state, compute errors, and reflect them on each field with `color="danger"` (colors the
input), `message` (the help text), and `messageColor="danger"` (colors the help text).

## Account settings

<ExampleMeta
  skill="bestax-form"
  skillHref="https://github.com/allxsmith/bestax/blob/main/skills/bestax-form/SKILL.md"
  model="Claude Opus 4.8"
  date="2026-06-27"
/>

### Prompt

```text
Build an account settings form with a bio, a timezone select, an email-digest
radio group, interest checkboxes, and toggle switches — following the bestax
form skill.
```

### Live form

```tsx live
function example() {
  const [bio, setBio] = useState('');
  const [timezone, setTimezone] = useState('utc');
  const [digest, setDigest] = useState('weekly');
  const [interests, setInterests] = useState(['react']);
  const [darkMode, setDarkMode] = useState(true);
  const [twoFactor, setTwoFactor] = useState(false);

  return (
    <form style={{ maxWidth: '32rem' }}>
      <TextArea
        label="Bio"
        value={bio}
        onChange={e => setBio(e.target.value)}
        rows={3}
        placeholder="Tell us about yourself"
      />
      <Select
        label="Timezone"
        value={timezone}
        onChange={e => setTimezone(e.target.value)}
      >
        <option value="utc">UTC</option>
        <option value="est">Eastern</option>
        <option value="pst">Pacific</option>
      </Select>
      <Field label="Email digest">
        <Radios name="digest" value={digest} onChange={setDigest}>
          <Radio value="daily">Daily</Radio>
          <Radio value="weekly">Weekly</Radio>
          <Radio value="never">Never</Radio>
        </Radios>
      </Field>
      <Field label="Interests">
        <Checkboxes name="interests" value={interests} onChange={setInterests}>
          <Checkbox value="react">React</Checkbox>
          <Checkbox value="bulma">Bulma</Checkbox>
          <Checkbox value="design">Design</Checkbox>
        </Checkboxes>
      </Field>
      <Field>
        <Switch
          checked={darkMode}
          onChange={e => setDarkMode(e.target.checked)}
          color="primary"
        >
          Dark mode
        </Switch>
      </Field>
      <Field>
        <Switch
          checked={twoFactor}
          onChange={e => setTwoFactor(e.target.checked)}
          color="success"
        >
          Two-factor authentication
        </Switch>
      </Field>
      <Button color="primary">Save settings</Button>
    </form>
  );
}
```

### Grouped controls

`Checkboxes` manages an **array** value; `Radios` manages a **single** value. Each child carries a
`value`, and the group reports the selection through `onChange`.

## Advanced inputs

<ExampleMeta
  skill="bestax-form"
  skillHref="https://github.com/allxsmith/bestax/blob/main/skills/bestax-form/SKILL.md"
  model="Claude Opus 4.8"
  date="2026-06-27"
/>

### Prompt

```text
Build a freelancer profile form using the advanced inputs: autocomplete, slider,
number input, star rating, and tag input — following the bestax form skill.
```

### Live form

```tsx live
function example() {
  const [skill, setSkill] = useState('');
  const [experience, setExperience] = useState(5);
  const [rateUsd, setRateUsd] = useState(75);
  const [quality, setQuality] = useState(4);
  const [tags, setTags] = useState(['typescript']);

  return (
    
      <Autocomplete
        label="Primary skill"
        value={skill}
        onInput={setSkill}
        onSelect={item =>
          setSkill(typeof item === 'string' ? item : (item?.value ?? ''))
        }
        data={['React', 'Vue', 'Svelte', 'Angular']}
        openOnFocus
      />
      <Slider
        label="Years of experience"
        value={experience}
        onChange={setExperience}
        min={0}
        max={20}
        tooltip="auto"
      />
      <Numberinput
        label="Hourly rate (USD)"
        value={rateUsd}
        onChange={setRateUsd}
        min={10}
        max={500}
        step={5}
      />
      <Rate
        label="Self-rated quality"
        value={quality}
        onChange={setQuality}
        max={5}
      />
      <Taginput
        label="Tech stack"
        value={tags}
        onChange={next =>
          setTags(next.map(t => (typeof t === 'string' ? t : t.value)))
        }
        data={['typescript', 'node', 'graphql', 'css']}
      />
    
  );
}
```

### Wiring notes

`Autocomplete` reports typing via `onInput` and a chosen suggestion via `onSelect`. `Taginput`'s
`onChange` yields tag objects-or-strings, so map them when you store plain strings. A dual-thumb
`Slider` needs the `range` prop.

## Files & scheduling

<ExampleMeta
  skill="bestax-form"
  skillHref="https://github.com/allxsmith/bestax/blob/main/skills/bestax-form/SKILL.md"
  model="Claude Opus 4.8"
  date="2026-06-27"
/>

### Prompt

```text
Build an onboarding form with a file upload plus date, time, and date-time
pickers — following the bestax form skill.
```

### Live form

```tsx live
function example() {
  const [date, setDate] = useState(null);
  const [time, setTime] = useState(null);
  const [appt, setAppt] = useState(null);

  return (
    
      <Field label="Profile photo">
        <File hasName buttonLabel="Choose a file…" />
      </Field>
      <DateInput label="Date of birth" value={date} onChange={setDate} />
      <TimeInput
        label="Preferred contact time"
        value={time}
        onChange={setTime}
      />
      <DateTimeInput label="Appointment" value={appt} onChange={setAppt} />
    
  );
}
```

### Controlled date & time

The date/time inputs are controlled with a `Date | null` value and an `onChange(date)` handler,
just like the text inputs — only the widget differs.

---

## Skills

# Bestax Agent Skills

Drop-in [Agent Skills](https://skills.sh/) that teach coding agents — Claude Code, Cursor, and
other skills.sh-compatible tools — how to build with **@allxsmith/bestax-bulma** the right way.

Install one with the [`skills`](https://skills.sh/) CLI:

```bash
npx skills add https://github.com/allxsmith/bestax --skill bestax-custom-component
npx skills add https://github.com/allxsmith/bestax --skill bestax-form
npx skills add https://github.com/allxsmith/bestax --skill bestax-theming
npx skills add https://github.com/allxsmith/bestax --skill bestax-layout-scaffold
```

Starting a new app? `pnpm create bestax@latest` offers to **preinstall these skills** into the
generated app's `.claude/skills/` (alongside a `CLAUDE.md`), so a Claude Code session picks them up
automatically — no manual `skills add` needed.

Then explore each skill — what it does, how to install it, and live examples:

- **[Custom Component](./custom-component)** — build a new custom component the bestax way
  (check for an existing one first, then the helper hooks + Bulma v1 SCSS pattern).
- **[Form](./form)** — build forms with the bestax form components and the validate-it-yourself
  error pattern (no form library).
- **[Theming](./theming)** — customize colors, branding, and dark mode by overriding Bulma's
  `--bulma-*` variables with the `Theme` component.
- **[Layout scaffold](./layout-scaffold)** — go from "build me a dashboard / landing page / catalog"
  to a complete responsive page using the layout archetypes.

---

## Layout scaffold

# Layout scaffold skill

The [`bestax-layout-scaffold`](https://github.com/allxsmith/bestax/blob/main/skills/bestax-layout-scaffold/SKILL.md)
skill turns a high-level request — "admin dashboard", "landing page", "login screen", "product
catalog" — into a complete, responsive page built from bestax-bulma layout components, in one shot.
It maps the request to one of four archetypes and builds it without asking layout questions.

## Install

```bash
npx skills add https://github.com/allxsmith/bestax --skill bestax-layout-scaffold
```

## App shell with sidebar

<ExampleMeta
  skill="bestax-layout-scaffold"
  skillHref="https://github.com/allxsmith/bestax/blob/main/skills/bestax-layout-scaffold/SKILL.md"
  model="Claude Opus 4.8"
  date="2026-06-27"
/>

### Prompt

```text
Build an admin dashboard shell with a fixed top nav and a sidebar menu —
following the bestax layout-scaffold skill.
```

### Live result

The shell structure — a `Navbar`, a narrow `Menu` column, and a main content column. This preview
uses a **non-fixed** navbar; the shippable version uses `fixed="top"` (see Generated code), which
needs `position: fixed` and a page-level class and therefore can't render inside this embed.

```tsx live
function example() {
  const [menuOpen, setMenuOpen] = useState(false);
  return (
    <>
      <Navbar color="dark">
        <Navbar.Brand>
          <Navbar.Item href="#">Acme Admin</Navbar.Item>
          <Navbar.Burger
            active={menuOpen}
            onClick={() => setMenuOpen(open => !open)}
            aria-label="menu"
          />
        </Navbar.Brand>
        <Navbar.Menu active={menuOpen}>
          <Navbar.End>
            <Navbar.Item href="#">Account</Navbar.Item>
          </Navbar.End>
        </Navbar.Menu>
      </Navbar>
      <Container fluid>
        <Columns>
          <Column size={3}>
            <Menu>
              <Menu.Label>General</Menu.Label>
              <Menu.List>
                <Menu.Item active href="#">
                  Dashboard
                </Menu.Item>
                <Menu.Item href="#">Customers</Menu.Item>
                <Menu.Item href="#">Orders</Menu.Item>
              </Menu.List>
            </Menu>
          </Column>
          <Column>
            <Box>
              <Title size="4">Dashboard</Title>
              Main content area.
            </Box>
          </Column>
        </Columns>
      </Container>
    </>
  );
}
```

### Generated code

The shippable version adds `fixed="top"` and the required `has-navbar-fixed-top` class on `<html>`
(see `examples/app-shell.tsx`).

```tsx

  Navbar,
  Menu,
  Container,
  Columns,
  Column,
  Section,
  Title,
  Box,
} from '@allxsmith/bestax-bulma';

export default function AdminShell() {
  const [menuOpen, setMenuOpen] = useState(false);

  // A fixed-top navbar needs `has-navbar-fixed-top` on <html> (Bulma requirement;
  // the library does not add it for you).
  useEffect(() => {
    document.documentElement.classList.add('has-navbar-fixed-top');
    return () =>
      document.documentElement.classList.remove('has-navbar-fixed-top');
  }, []);

  return (
    <>
      <Navbar fixed="top" color="dark">
        <Navbar.Brand>
          <Navbar.Item href="#">Acme Admin</Navbar.Item>
          <Navbar.Burger
            active={menuOpen}
            onClick={() => setMenuOpen(open => !open)}
            aria-label="menu"
            aria-expanded={menuOpen}
          />
        </Navbar.Brand>
        <Navbar.Menu active={menuOpen}>
          <Navbar.End>
            <Navbar.Item href="#">Account</Navbar.Item>
          </Navbar.End>
        </Navbar.Menu>
      </Navbar>

      <Container fluid>
        <Columns>
          <Column size={3} sizeWidescreen={2}>
            <Menu>
              <Menu.Label>General</Menu.Label>
              <Menu.List>
                <Menu.Item active href="#">
                  Dashboard
                </Menu.Item>
                <Menu.Item href="#">Customers</Menu.Item>
              </Menu.List>
            </Menu>
          </Column>
          <Column>
            <Section>
              <Title size="3">Dashboard</Title>
              <Box>Main content area.</Box>
            </Section>
          </Column>
        </Columns>
      </Container>
    </>
  );
}
```

### Responsive

The navbar collapses to a burger on mobile; the sidebar and content columns sit side by side on
tablet and up, and stack on mobile.

## Marketing / landing

<ExampleMeta
  skill="bestax-layout-scaffold"
  skillHref="https://github.com/allxsmith/bestax/blob/main/skills/bestax-layout-scaffold/SKILL.md"
  model="Claude Opus 4.8"
  date="2026-06-27"
/>

### Prompt

```text
Build a marketing landing page with a hero, a three-feature section, and a
footer — following the bestax layout-scaffold skill.
```

### Live result

```tsx live
function example() {
  return (
    <>
      <Hero color="primary" size="medium">
        <Hero.Body>
          <Container textAlign="centered">
            <Title size="2">Ship faster with Acme</Title>
            <SubTitle size="4">
              The all-in-one platform for modern teams.
            </SubTitle>
            <Buttons isCentered>
              <Button color="light" size="large">
                Get started
              </Button>
            </Buttons>
          </Container>
        </Hero.Body>
      </Hero>
      <Section>
        <Container>
          <Columns>
            <Column>
              <Box>
                <Title size="5">Fast</Title>
                <Content>Ship pages in minutes.</Content>
              </Box>
            </Column>
            <Column>
              <Box>
                <Title size="5">Responsive</Title>
                <Content>Looks right on every screen.</Content>
              </Box>
            </Column>
            <Column>
              <Box>
                <Title size="5">Composable</Title>
                <Content>Build from small pieces.</Content>
              </Box>
            </Column>
          </Columns>
        </Container>
      </Section>
    </>
  );
}
```

### Responsive

Sections stack vertically; the feature `Columns` collapse to one per row on mobile.

## Centered single-column

<ExampleMeta
  skill="bestax-layout-scaffold"
  skillHref="https://github.com/allxsmith/bestax/blob/main/skills/bestax-layout-scaffold/SKILL.md"
  model="Claude Opus 4.8"
  date="2026-06-27"
/>

### Prompt

```text
Build a centered login page — following the bestax layout-scaffold skill.
```

### Live result

```tsx live
function example() {
  return (
    <Section>
      <Container>
        <Columns isCentered>
          <Column size="half" sizeWidescreen="one-third">
            <Box>
              <Title size="4" textAlign="centered">
                Sign in
              </Title>
              <Input label="Email" type="email" iconLeftName="envelope" />
              <Input label="Password" type="password" iconLeftName="lock" />
              <Button color="primary" isFullWidth mt="4">
                Sign in
              </Button>
            </Box>
          </Column>
        </Columns>
      </Container>
    </Section>
  );
}
```

### Responsive

The centered column is narrow on desktop and full width on mobile.

## Card grid / catalog

<ExampleMeta
  skill="bestax-layout-scaffold"
  skillHref="https://github.com/allxsmith/bestax/blob/main/skills/bestax-layout-scaffold/SKILL.md"
  model="Claude Opus 4.8"
  date="2026-06-27"
/>

### Prompt

```text
Build a product catalog as a responsive grid of cards — following the bestax
layout-scaffold skill.
```

### Live result

```tsx live
function example() {
  const items = [
    { id: 1, name: 'Aurora Lamp', price: '$48', seed: 1 },
    { id: 2, name: 'Drift Chair', price: '$220', seed: 2 },
    { id: 3, name: 'Stone Mug', price: '$18', seed: 3 },
  ];
  return (
    <Section>
      <Container>
        <Columns isMultiline>
          {items.map(item => (
            <Column
              key={item.id}
              sizeMobile="full"
              sizeTablet="half"
              sizeDesktop="one-third"
            >
              <Card
                image={`https://picsum.photos/seed/${item.seed}/600/400`}
                imageAlt={item.name}
                header={item.name}
                footer={{item.price}}
              >
                A short product description.
              </Card>
            </Column>
          ))}
        </Columns>
      </Container>
    </Section>
  );
}
```

### Responsive

`isMultiline` wraps cards onto new rows; the `size*` props set one card per row on mobile, two on
tablet, three on desktop.

---

## Theming

# Theming skill

The [`bestax-theming`](https://github.com/allxsmith/bestax/blob/main/skills/bestax-theming/SKILL.md)
skill teaches an agent to customize colors, branding, and dark mode of an app built with
`@allxsmith/bestax-bulma`. Bulma 1.x is themed through `--bulma-*` CSS variables; recolor a brand
color by overriding its hue/saturation/lightness trio with the exported `Theme` component.

## Install

```bash
npx skills add https://github.com/allxsmith/bestax --skill bestax-theming
```

## Custom brand theme

<ExampleMeta
  skill="bestax-theming"
  skillHref="https://github.com/allxsmith/bestax/blob/main/skills/bestax-theming/SKILL.md"
  model="Claude Opus 4.8"
  date="2026-06-27"
/>

### Prompt

```text
Set up a custom brand theme for an app built with @allxsmith/bestax-bulma —
override the brand colors and the corner radius — following the bestax theming
skill.
```

### Live result

The wrapped section below recolors via a **scoped** `<Theme>` (no `isRoot`), so the override
applies only to its children.

```tsx live
function example() {
  return (
    <Theme
      infoH="291"
      infoS="70%"
      infoL="50%"
      linkH="291"
      linkS="70%"
      linkL="50%"
      bulmaVars={{ '--bulma-radius': '9999px' }}
    >
      
        <Button color="info">Info button</Button>
        <Button color="link">Link button</Button>
        <Tag color="info">Themed tag</Tag>
      
    </Theme>
  );
}
```

:::note
This live preview pins `--bulma-primary-*`, so the demo recolors `info`/`link` to show the effect.
In a real app, override `primaryH`/`primaryS`/`primaryL` the same way to recolor the brand primary.
:::

### Generated code

<Tabs>
<TabItem value="root" label="App root (global)">

```tsx

// Wrap the app once. `isRoot` writes the variables to :root globally.
export function ThemedApp({ children }: { children: React.ReactNode }) {
  return (
    <Theme
      isRoot
      primaryH="265"
      primaryS="65%"
      primaryL="55%"
      linkH="200"
      linkS="80%"
      linkL="45%"
      bulmaVars={{
        '--bulma-radius': '0.75rem',
        '--bulma-family-primary': "'Inter', system-ui, sans-serif",
      }}
    >
      {children}
    </Theme>
  );
}
```

</TabItem>
<TabItem value="scoped" label="Scoped override">

```tsx

// Theme one section; the rest of the app is untouched (no `isRoot`).
export function PromoPanel() {
  return (
    <Theme primaryH="16" primaryS="85%" primaryL="55%">
      <Box>
        <Button color="primary">Warm primary, only here</Button>
      </Box>
    </Theme>
  );
}
```

</TabItem>
</Tabs>

Bulma derives every shade and the light/dark/invert variants from the `--bulma-<color>-h/-s/-l`
trio, so overriding the trio recolors the whole palette. Non-color tokens (radius, fonts, sizes)
go through `bulmaVars`, keyed by their real `--bulma-*` names.

## Dark mode

<ExampleMeta
  skill="bestax-theming"
  skillHref="https://github.com/allxsmith/bestax/blob/main/skills/bestax-theming/SKILL.md"
  model="Claude Opus 4.8"
  date="2026-06-27"
/>

### Prompt

```text
Add a light/dark mode toggle to an app built with @allxsmith/bestax-bulma —
there is no shipped dark-mode component — following the bestax theming skill.
```

### Generated code

The `Theme` component drives dark mode via its `colorMode` prop — no manual DOM work.

```tsx

  Theme,
  Box,
  Button,
  Title,
  Notification,
} from '@allxsmith/bestax-bulma';

type Mode = 'light' | 'dark' | 'system';

export function DarkModeToggle() {
  const [mode, setMode] = useState<Mode>('system');

  return (
    <Theme isRoot colorMode={mode}>
      <Box>
        <Title size="5">Color mode: {mode}</Title>
        <Notification color="info">
          Components follow the current Bulma color scheme.
        </Notification>
        <Button color="primary" onClick={() => setMode('light')}>
          Light
        </Button>
        <Button color="primary" onClick={() => setMode('dark')}>
          Dark
        </Button>
        <Button onClick={() => setMode('system')}>System</Button>
      </Box>
    </Theme>
  );
}
```

### How it works

`Theme`'s `colorMode` prop (`'light' | 'dark' | 'system'`) writes Bulma's `data-theme` attribute on
`<html>`, so the whole document follows the chosen scheme — global, even on a scoped `Theme`.
`'system'` removes the attribute so Bulma follows the OS `prefers-color-scheme`. Brand overrides
from `<Theme isRoot>` still apply on top of either scheme.

:::note Why there's no live demo here
`colorMode` flips the page-level `data-theme` on `<html>` — the same attribute this documentation
site uses for its own light/dark mode, and the embedded previews are sandboxed to the site theme.
A live toggle would flip the entire site, not a contained example. To see it: toggle this site's
dark mode (top-right of the navbar) to view components in dark, or run the **Helpers / Theme →
DarkMode** story in Storybook.
:::

---

## Components Intro



---

## Column


## Overview

The `Column` component provides a single responsive layout column using Bulma's flexbox-based column system. It supports all Bulma column size modifiers, responsive sizes and offsets, color/background helpers, "narrow" behavior, and utility/HTML props. Use together with [`Columns`](./columns.md) for powerful, declarative layouts.

---

## Import

```tsx

```

---

## Props

| Prop                 | Type                                                                                                                                                                                                                                                                                     | Description                                             |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `className`          | `string`                                                                                                                                                                                                                                                                                 | Additional CSS classes for the column.                  |
| `textColor`          | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | Text color.                                             |
| `color`              | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`                                                                                                                                                                                                          | Bulma color modifier for the column.                    |
| `bgColor`            | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | Background color.                                       |
| `size`               | number \| `'full'` \| `'half'` \| `'one-third'` \| `'two-thirds'` \| `'one-quarter'` \| ...                                                                                                                                                                                              | Column size (see Bulma docs).                           |
| `sizeMobile`         | as above                                                                                                                                                                                                                                                                                 | Size for mobile breakpoint.                             |
| `sizeTablet`         | as above                                                                                                                                                                                                                                                                                 | Size for tablet breakpoint.                             |
| `sizeDesktop`        | as above                                                                                                                                                                                                                                                                                 | Size for desktop breakpoint.                            |
| `sizeWidescreen`     | as above                                                                                                                                                                                                                                                                                 | Size for widescreen breakpoint.                         |
| `sizeFullhd`         | as above                                                                                                                                                                                                                                                                                 | Size for fullhd breakpoint.                             |
| `offset`             | as above                                                                                                                                                                                                                                                                                 | Offset for column.                                      |
| `offsetMobile`       | as above                                                                                                                                                                                                                                                                                 | Offset for mobile.                                      |
| `offsetTablet`       | as above                                                                                                                                                                                                                                                                                 | Offset for tablet.                                      |
| `offsetDesktop`      | as above                                                                                                                                                                                                                                                                                 | Offset for desktop.                                     |
| `offsetWidescreen`   | as above                                                                                                                                                                                                                                                                                 | Offset for widescreen.                                  |
| `offsetFullhd`       | as above                                                                                                                                                                                                                                                                                 | Offset for fullhd.                                      |
| `isNarrow`           | `boolean`                                                                                                                                                                                                                                                                                | Column is only as wide as its content.                  |
| `isNarrowMobile`     | `boolean`                                                                                                                                                                                                                                                                                | Narrow on mobile.                                       |
| `isNarrowTablet`     | `boolean`                                                                                                                                                                                                                                                                                | Narrow on tablet.                                       |
| `isNarrowTouch`      | `boolean`                                                                                                                                                                                                                                                                                | Narrow on touch devices.                                |
| `isNarrowDesktop`    | `boolean`                                                                                                                                                                                                                                                                                | Narrow on desktop.                                      |
| `isNarrowWidescreen` | `boolean`                                                                                                                                                                                                                                                                                | Narrow on widescreen.                                   |
| `isNarrowFullhd`     | `boolean`                                                                                                                                                                                                                                                                                | Narrow on fullhd.                                       |
| `children`           | `React.ReactNode`                                                                                                                                                                                                                                                                        | Children to render inside the column.                   |
| ...                  | All Bulma helper and HTML props                                                                                                                                                                                                                                                          | (See [Helper Props](/docs/api/helpers/usebulmaclasses)) |

---

## Usage

### Basic Columns Example

This example shows the `Column` component used within a `Columns` container. Each `Column` can accept Bulma size, color, and offset props to control its width and appearance. Use this pattern for building flexible horizontal layouts with multiple columns.

```tsx live

<Columns>
  <Column>
    <Notification color="primary">First column</Notification>
  </Column>
  <Column>
    <Notification color="info">Second column</Notification>
  </Column>
  <Column>
    <Notification color="link">Third column</Notification>
  </Column>
  <Column>
    <Notification color="warning">Fourth column</Notification>
  </Column>
</Columns>;
```

---

### Column Sizes

This section demonstrates the various size options for columns. Sizes can be set using Bulma's fractional values or keywords like `full`, `half`, `one-third`, etc. Combine these with offset props to control the column's position within the row.

```tsx live
<>
  <Columns>
    <Column size="four-fifths">
      <Notification color="primary">is-four-fifths</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
  </Columns>

  <Columns>
    <Column size="three-quarters">
      <Notification color="primary">is-three-quarters</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
  </Columns>

  <Columns>
    <Column size="two-thirds">
      <Notification color="primary">is-two-thirds</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
  </Columns>

  <Columns>
    <Column size="three-fifths">
      <Notification color="primary">is-three-fifths</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
  </Columns>

  <Columns>
    <Column size="half">
      <Notification color="primary">is-half</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
  </Columns>

  <Columns>
    <Column size="two-fifths">
      <Notification color="primary">is-two-fifths</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
  </Columns>

  <Columns>
    <Column size="one-third">
      <Notification color="primary">is-one-third</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
  </Columns>

  <Columns>
    <Column size="one-quarter">
      <Notification color="primary">is-one-quarter</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
  </Columns>

  <Columns>
    <Column size="one-fifth">
      <Notification color="primary">is-one-fifth</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
    <Column>
      <Notification color="primary">Auto</Notification>
    </Column>
  </Columns>
</>
```

---

### 12 Column System

In Bulma's 12 column system, you can specify column sizes from 1 to 12, allowing for a wide range of layout possibilities. This example demonstrates how each column size behaves, including automatic sizing for remaining space.

```tsx live
<>
  {[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12].map(num => (
    <Columns key={num}>
      <Column size={num}>
        <Notification color="primary">
          {num === 1 ? 1 : `is-${num}`}
        </Notification>
      </Column>
      {num === 11 && (
        <Column>
          <Notification color="primary">1</Notification>
        </Column>
      )}
      {num < 11 && (
        <Column>
          <Notification color="primary">Auto</Notification>
        </Column>
      )}
      {num < 10 && (
        <Column>
          <Notification color="primary">Auto</Notification>
        </Column>
      )}
    </Columns>
  ))}
</>
```

---

### Responsive Column Sizes

Columns can have different sizes at different breakpoints, allowing for a fully responsive design. This example shows a column that changes size from mobile to desktop views.

```tsx live
<Columns isMobile>
  <Column
    sizeMobile="three-quarters"
    sizeTablet="two-thirds"
    sizeDesktop="half"
    sizeWidescreen="one-third"
    sizeFullhd="one-quarter"
  >
    <Notification color="primary">
      <code>sizeMobile="three-quarters"</code>
      
      <code>sizeTablet="two-thirds"</code>
      
      <code>sizeDesktop="half"</code>
      
      <code>sizeWidescreen="one-third"</code>
      
      <code>sizeFullhd="one-quarter"</code>
    </Notification>
  </Column>
  <Column>
    <Notification color="primary">2</Notification>
  </Column>
  <Column>
    <Notification color="primary">3</Notification>
  </Column>
  <Column>
    <Notification color="primary">4</Notification>
  </Column>
  <Column>
    <Notification color="primary">5</Notification>
  </Column>
</Columns>
```

---

### Offsets

Offsets are used to push columns to the right, creating space between columns. This is particularly useful for centering columns or creating specific layouts.

```tsx live
<>
  <Columns isMobile>
    <Column size="half" offset="one-quarter">
      <Notification color="primary">is-half is-offset-one-quarter</Notification>
    </Column>
  </Columns>
  <Columns isMobile>
    <Column size="three-fifths" offset="one-fifth">
      <Notification color="primary">
        is-three-fifths is-offset-one-fifth
      </Notification>
    </Column>
  </Columns>
  <Columns isMobile>
    <Column size={4} offset={8}>
      <Notification color="primary">is-4 is-offset-8</Notification>
    </Column>
  </Columns>
  <Columns isMobile>
    <Column size={11} offset={1}>
      <Notification color="primary">is-11 is-offset-1</Notification>
    </Column>
  </Columns>
</>
```

---

### Narrow Columns

Narrow columns only take up as much width as their content, which can be useful for sidebar menus, buttons, or any content that doesn't need to stretch the full width of the column.

```tsx live
<Columns>
  <Column isNarrow>
    <Notification color="primary" style={{ width: 180 }}>
      Narrow column
      
      This column is only as wide as it needs to be, 180px wide.
    </Notification>
  </Column>
  <Column>
    <Notification color="primary">
      Flexible column
      
      This column will take up the remaining space available.
    </Notification>
  </Column>
</Columns>
```

---

## Notes

- Use the `Columns` component as a parent for `Column` children for proper row-column behavior.
- All column, offset, and narrow props support responsive variants.
- Combine with [Bulma helper props](/docs/api/helpers/usebulmaclasses) for utility-first styling.
- All standard `` HTML props are supported.

---

## See Also

- [Columns container](./columns.md)
- [Bulma Columns Documentation](https://bulma.io/documentation/columns/)
- [Storybook: Column Story](https://bestax.io/storybook/?path=/story/columns-column--default)

---

## Columns


## Overview

The `Columns` component provides Bulma's flexible, responsive grid container for aligning and distributing [`Column`](./column.md) components. It supports wrapping, gap control, centering, vertical alignment, responsive breakpoints, and all Bulma/utility helper props. Use it as the parent for one or more `Column` children.

---

## Import

```tsx

```

---

## Props

| Prop                | Type                                                                                                                                                                                                                                                                                     | Description                                          |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `className`         | `string`                                                                                                                                                                                                                                                                                 | Additional CSS classes for the columns container.    |
| `textColor`         | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | Text color.                                          |
| `color`             | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`                                                                                                                                                                                                          | Bulma color modifier for all columns.                |
| `bgColor`           | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | Background color for all columns.                    |
| `isCentered`        | `boolean`                                                                                                                                                                                                                                                                                | Horizontally center columns within the container.    |
| `isGapless`         | `boolean`                                                                                                                                                                                                                                                                                | Remove gap between columns.                          |
| `isMultiline`       | `boolean`                                                                                                                                                                                                                                                                                | Allow columns to wrap to multiple lines.             |
| `isVCentered`       | `boolean`                                                                                                                                                                                                                                                                                | Vertically center columns within the container.      |
| `isMobile`          | `boolean`                                                                                                                                                                                                                                                                                | Apply columns layout on mobile and up.               |
| `isDesktop`         | `boolean`                                                                                                                                                                                                                                                                                | Apply columns layout on desktop and up.              |
| `gapSize`           | number \| string (0-8)                                                                                                                                                                                                                                                                   | Gap size for all breakpoints.                        |
| `gapSizeMobile`     | number \| string (0-8)                                                                                                                                                                                                                                                                   | Gap size for mobile.                                 |
| `gapSizeTablet`     | number \| string (0-8)                                                                                                                                                                                                                                                                   | Gap size for tablet.                                 |
| `gapSizeDesktop`    | number \| string (0-8)                                                                                                                                                                                                                                                                   | Gap size for desktop.                                |
| `gapSizeWidescreen` | number \| string (0-8)                                                                                                                                                                                                                                                                   | Gap size for widescreen.                             |
| `gapSizeFullhd`     | number \| string (0-8)                                                                                                                                                                                                                                                                   | Gap size for fullhd.                                 |
| `children`          | `React.ReactNode`                                                                                                                                                                                                                                                                        | Columns to render within the container.              |
| ...                 | All Bulma helper and HTML props                                                                                                                                                                                                                                                          | (See [Helper Props](../api/helpers/usebulmaclasses)) |

---

## Usage

### Basic Columns

This example shows the `Columns` component containing multiple `Column` children. Each `Column` can contain any content, and the columns will be distributed evenly across the container. Use this pattern for flexible horizontal layouts.

```tsx live
<Columns>
  <Column>
    <Notification color="primary">First column</Notification>
  </Column>
  <Column>
    <Notification color="info">Second column</Notification>
  </Column>
  <Column>
    <Notification color="link">Third column</Notification>
  </Column>
  <Column>
    <Notification color="warning">Fourth column</Notification>
  </Column>
</Columns>
```

---

### Columns on Mobile and Desktop

This example demonstrates the `isMobile` prop, which enables the columns layout on mobile screens and up. Use this to ensure your layout is responsive and adapts to smaller devices.

```tsx live
<>
  {
    // Columns enabled on mobile screens and up
  }
  <Columns isMobile>
    <Column>
      <Notification color="primary">1</Notification>
    </Column>
    <Column>
      <Notification color="primary">2</Notification>
    </Column>
    <Column>
      <Notification color="primary">3</Notification>
    </Column>
    <Column>
      <Notification color="primary">4</Notification>
    </Column>
    <Column>
      <Notification color="primary">5</Notification>
    </Column>
  </Columns>

  {
    // Columns enabled on desktop screens and up
  }
  <Columns isDesktop>
    <Column>
      <Notification color="primary">1</Notification>
    </Column>
    <Column>
      <Notification color="primary">2</Notification>
    </Column>
    <Column>
      <Notification color="primary">3</Notification>
    </Column>
    <Column>
      <Notification color="primary">4</Notification>
    </Column>
    <Column>
      <Notification color="primary">5</Notification>
    </Column>
  </Columns>
</>
```

---

### Different Column Sizes Per Breakpoint

This example demonstrates how to set different column sizes for various breakpoints using the `size` props. This allows for a highly responsive design that can adapt to different screen sizes.

```tsx live
<Columns isMobile>
  <Column
    sizeMobile="three-quarters"
    sizeTablet="two-thirds"
    sizeDesktop="half"
    sizeWidescreen="one-third"
    sizeFullhd="one-quarter"
  >
    <Notification color="primary">
      <code>sizeMobile="three-quarters"</code>
      
      <code>sizeTablet="two-thirds"</code>
      
      <code>sizeDesktop="half"</code>
      
      <code>sizeWidescreen="one-third"</code>
      
      <code>sizeFullhd="one-quarter"</code>
    </Notification>
  </Column>
  <Column>
    <Notification color="primary">2</Notification>
  </Column>
  <Column>
    <Notification color="primary">3</Notification>
  </Column>
  <Column>
    <Notification color="primary">4</Notification>
  </Column>
  <Column>
    <Notification color="primary">5</Notification>
  </Column>
</Columns>
```

---

### Nested Columns

This example shows how columns can be nested within each other. Nested columns inherit the properties of their parent columns, allowing for complex and flexible layouts.

```tsx live
<Columns>
  <Column>
    <Notification color="primary">First column</Notification>
    <Columns isMobile>
      <Column>
        <Notification color="primary">First nested column</Notification>
      </Column>
      <Column>
        <Notification color="primary">Second nested column</Notification>
      </Column>
    </Columns>
  </Column>
  <Column>
    <Notification color="primary">Second column</Notification>
    <Columns isMobile>
      <Column size="half">
        <Notification color="primary">50%</Notification>
      </Column>
      <Column>
        <Notification color="primary">Auto</Notification>
      </Column>
      <Column>
        <Notification color="primary">Auto</Notification>
      </Column>
    </Columns>
  </Column>
</Columns>
```

---

### Gap Sizes & Responsive Gaps

This example demonstrates the use of the `gapSize` prop to control the space between columns. Responsive gap sizes can also be set for different screen sizes.

```tsx live
<>
  <Columns gapSize={0}>
    <Column>
      <Notification color="primary" radius="radiusless">
        gapSize=0
      </Notification>
    </Column>
    <Column>
      <Notification color="info" radius="radiusless">
        gapSize=0
      </Notification>
    </Column>
  </Columns>
  <Columns gapSize={3}>
    <Column>
      <Notification color="primary">gapSize=3</Notification>
    </Column>
    <Column>
      <Notification color="info">gapSize=3</Notification>
    </Column>
  </Columns>
  <Columns gapSizeMobile={1} gapSizeTablet={3} gapSizeDesktop={6}>
    <Column>
      <Notification color="primary">
        gapSizeMobile=1 gapSizeTablet=3 gapSizeDesktop=6
      </Notification>
    </Column>
    <Column>
      <Notification color="info">
        gapSizeMobile=1 gapSizeTablet=3 gapSizeDesktop=6
      </Notification>
    </Column>
  </Columns>
</>
```

---

### Offsets

This example shows how to use the `offset` prop to create space between columns. Offsets can be used to center columns or create more complex layouts.

```tsx live
<>
  <Columns isMobile>
    <Column size="half" offset="one-quarter">
      <Notification color="primary">
        <code>size="half" offset="one-quarter"</code>
      </Notification>
    </Column>
  </Columns>
  <Columns isMobile>
    <Column size="three-fifths" offset="one-fifth">
      <Notification color="primary">
        <code>size="three-fifths" offset="one-fifth"</code>
      </Notification>
    </Column>
  </Columns>
  <Columns isMobile>
    <Column size={4} offset={8}>
      <Notification color="primary">
        <code>
          size={4} offset={8}
        </code>
      </Notification>
    </Column>
  </Columns>
  <Columns isMobile>
    <Column size={11} offset={1}>
      <Notification color="primary">
        <code>size=11 offset=1</code>
      </Notification>
    </Column>
  </Columns>
</>
```

---

### Narrow Columns

This example demonstrates the `isNarrow` prop, which can be applied to columns to make them take up only as much space as their content. This is useful for sidebar or menu columns.

```tsx live
<Columns>
  <Column isNarrow>
    <Notification color="primary" style={{ width: 200 }}>
      Narrow column
      
      This column is only 200px wide.
    </Notification>
  </Column>
  <Column>
    <Notification color="primary">
      Flexible column
      
      This column will take up the remaining space available.
    </Notification>
  </Column>
</Columns>
```

---

### Gapless Columns

This example shows how to create columns without any gaps between them using the `isGapless` prop. This can be useful for creating a more seamless look.

```tsx live
<Columns isGapless>
  <Column>
    <Notification color="primary" radius="radiusless">
      1
    </Notification>
  </Column>
  <Column>
    <Notification color="info" radius="radiusless">
      2
    </Notification>
  </Column>
  <Column>
    <Notification color="success" radius="radiusless">
      3
    </Notification>
  </Column>
  <Column>
    <Notification color="warning" radius="radiusless">
      4
    </Notification>
  </Column>
</Columns>
```

---

### Multiline and Gapless

This example demonstrates using the `isMultiline` and `isGapless` props together. This allows for a grid that wraps onto multiple lines without any gaps between the columns.

```tsx live
<Columns isGapless isMultiline isMobile>
  <Column size="one-quarter">
    <Notification color="primary" radius="radiusless">
      is-one-quarter
    </Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="info" radius="radiusless">
      is-one-quarter
    </Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="success" radius="radiusless">
      is-one-quarter
    </Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="warning" radius="radiusless">
      is-one-quarter
    </Notification>
  </Column>
  <Column size="half">
    <Notification color="danger" radius="radiusless">
      is-half
    </Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="link" radius="radiusless">
      is-one-quarter
    </Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="dark" radius="radiusless">
      is-one-quarter
    </Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="primary" radius="radiusless">
      is-one-quarter
    </Notification>
  </Column>
  <Column>
    <Notification color="info" radius="radiusless">
      Auto
    </Notification>
  </Column>
</Columns>
```

---

### Variable Gap

This example demonstrates how to use the `gapSize` prop to create columns with variable widths. This can be useful for creating layouts with sidebars or varying content widths.

```tsx live
<>
  <Columns gapSize={2}>
    <Column size={3}>
      <Notification color="primary" textAlign="centered">
        Side
      </Notification>
    </Column>
    <Column size={9}>
      <Notification color="primary" textAlign="centered">
        Main
      </Notification>
    </Column>
  </Columns>
  <Columns gapSize={2}>
    <Column size={4}>
      <Notification color="primary" textAlign="centered">
        Three columns
      </Notification>
    </Column>
    <Column size={4}>
      <Notification color="primary" textAlign="centered">
        Three columns
      </Notification>
    </Column>
    <Column size={4}>
      <Notification color="primary" textAlign="centered">
        Three columns
      </Notification>
    </Column>
  </Columns>
  <Columns gapSize={2}>
    {Array.from({ length: 6 }).map((_, i) => (
      <Column key={i + 1}>
        <Notification color="primary" textAlign="centered">
          {i + 1}
        </Notification>
      </Column>
    ))}
  </Columns>
</>
```

---

### Breakpoint Based Column Gaps

This example shows how to set different gap sizes for different breakpoints. This allows for fine-tuned control over the layout on various screen sizes.

```tsx live
<Columns
  gapSizeMobile={1}
  gapSizeTablet={4}
  gapSizeDesktop={3}
  gapSizeWidescreen={8}
  gapSizeFullhd={2}
>
  {[...Array(3)].map((_, idx) => (
    <Column key={idx}>
      <Notification color="primary">Column</Notification>
    </Column>
  ))}
</Columns>
```

---

### Vertical Alignment

This example demonstrates the `isVCentered` prop, which vertically centers the content of the columns. This can be useful for creating evenly aligned layouts.

```tsx live
<Columns isVCentered>
  <Column size={8}>
    <Notification color="primary">First column</Notification>
  </Column>
  <Column>
    <Notification color="primary">
      Can you see the vertical alignment? It should be really noticable with
      these two columns.
    </Notification>
  </Column>
</Columns>
```

---

### Multiline Columns

This example shows how columns can automatically wrap onto multiple lines when there isn't enough space to display them in a single line. This is controlled by the `isMultiline` prop.

```tsx live
<Columns isMultiline isMobile>
  <Column size="one-quarter">
    <Notification color="primary">
      <code>is-one-quarter</code>
    </Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="primary">
      <code>is-one-quarter</code>
    </Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="primary">
      <code>is-one-quarter</code>
    </Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="primary">
      <code>is-one-quarter</code>
    </Notification>
  </Column>
  <Column size="half">
    <Notification color="primary">
      <code>is-half</code>
    </Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="primary">
      <code>is-one-quarter</code>
    </Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="primary">
      <code>is-one-quarter</code>
    </Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="primary">
      <code>is-one-quarter</code>
    </Notification>
  </Column>
  <Column>
    <Notification color="primary">Auto</Notification>
  </Column>
</Columns>
```

---

### Centering Columns

This example demonstrates the `isCentered` prop, which horizontally centers the columns within the container. This is particularly useful for creating balanced layouts.

```tsx live
<Columns isMobile isCentered>
  <Column size="half">
    <Notification color="primary">
      <code className="html">is-half</code>
      
    </Notification>
  </Column>
</Columns>
```

---

### Multiline Centered Columns

This example shows how to combine the `isCentered` prop with multiline columns. This allows for a centered, responsive grid that adapts to different screen sizes.

```tsx live
<Columns isMobile isMultiline isCentered>
  <Column isNarrow>
    <Notification color="primary">
      <code className="html">is-narrow</code>
      
      First Column
    </Notification>
  </Column>
  <Column isNarrow>
    <Notification color="primary">
      <code className="html">is-narrow</code>
      
      Our Second Column
    </Notification>
  </Column>
  <Column isNarrow>
    <Notification color="primary">
      <code className="html">is-narrow</code>
      
      Third Column
    </Notification>
  </Column>
  <Column isNarrow>
    <Notification color="primary">
      <code className="html">is-narrow</code>
      
      The Fourth Column
    </Notification>
  </Column>
  <Column isNarrow>
    <Notification color="primary">
      <code className="html">is-narrow</code>
      
      Fifth Column
    </Notification>
  </Column>
</Columns>
```

---

## Notes

- Use `Column` as a direct child of `Columns` for proper grid behavior.
- All gap, centering, and alignment props support responsive variants.
- Combine with [Bulma helper props](../api/helpers/usebulmaclasses) for utility-first styling.
- All standard `` HTML props are supported.

---

## See Also

- [Column component](./column.md)
- [Bulma Columns Documentation](https://bulma.io/documentation/columns/)
- [Storybook: Columns Story](https://bestax.io/storybook/?path=/story/columns-columns--mobile-columns)

---

## Breadcrumb


## Overview

The `Breadcrumb` component renders a Bulma-styled breadcrumb navigation. It supports alignment, separator styles, sizes, and works naturally with icons and text. Use it to help users understand their location in an app or website.

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                         | Description                                              |
| ----------- | -------------------------------------------- | -------------------------------------------------------- |
| `className` | `string`                                     | Additional CSS classes to apply.                         |
| `alignment` | `'centered' \| 'right'`                      | Alignment of the breadcrumb (`is-centered`, `is-right`). |
| `separator` | `'arrow' \| 'bullet' \| 'dot' \| 'succeeds'` | Type of separator between breadcrumb items.              |
| `size`      | `'small' \| 'medium' \| 'large'`             | Breadcrumb size.                                         |
| `children`  | `React.ReactNode`                            | Breadcrumb items (``s with `` or ``).       |
| ...         | All standard HTML and Bulma helper props     | (See [Helper Props](../helpers/usebulmaclasses))         |

---

## Usage

### Default Breadcrumb

To create a navigation trail, use the `Breadcrumb` component with a series of `` elements as children. You can include icons, text, and links for each breadcrumb item. This pattern helps users understand their current location within the app and easily navigate back to previous sections. Customize the appearance using props like `alignment`, `separator`, and `size` for different layouts and styles.

```tsx live
<Breadcrumb>
  
    
      <Icon library="fa" name="home" ariaLabel="home icon" /> Home
    
  
  
    
      <Icon library="fa" name="folder" ariaLabel="category icon" /> Category
    
  
  
    
      <Icon library="fa" name="file" ariaLabel="item icon" /> Item
    
  
</Breadcrumb>
```

---

### Centered Alignment

Set the `alignment` prop to `centered` to center the breadcrumb navigation horizontally. This is useful for layouts where you want the navigation to be visually balanced in the middle of the page or section. All other features, such as icons and separators, remain available.

```tsx live
<Breadcrumb alignment="centered">
  
    
      <Icon library="fa" name="home" ariaLabel="home icon" /> Home
    
  
  
    
      <Icon library="fa" name="folder" ariaLabel="category icon" /> Category
    
  
  
    
      <Icon library="fa" name="file" ariaLabel="item icon" /> Item
    
  
</Breadcrumb>
```

---

### Right Alignment

Use the `alignment` prop with the value `right` to align the breadcrumb navigation to the right edge of its container. This is helpful for layouts where navigation should be flush with the right margin, such as in toolbars or headers.

```tsx live
<Breadcrumb alignment="right">
  
    
      <Icon library="fa" name="home" ariaLabel="home icon" /> Home
    
  
  
    
      <Icon library="fa" name="folder" ariaLabel="category icon" /> Category
    
  
  
    
      <Icon library="fa" name="file" ariaLabel="item icon" /> Item
    
  
</Breadcrumb>
```

---

### Arrow Separator

Set the `separator` prop to `arrow` to use arrow icons between breadcrumb items. This style is visually clear and works well for step-by-step navigation.

```tsx live
<Breadcrumb separator="arrow">
  
    
      <Icon library="fa" name="home" ariaLabel="home icon" /> Home
    
  
  
    
      <Icon library="fa" name="folder" ariaLabel="category icon" /> Category
    
  
  
    
      <Icon library="fa" name="file" ariaLabel="item icon" /> Item
    
  
</Breadcrumb>
```

---

### Bullet Separator

Use the `separator` prop with the value `bullet` to display bullet points between breadcrumb items. This provides a subtle, minimalist look for navigation trails.

```tsx live
<Breadcrumb separator="bullet">
  
    
      <Icon library="fa" name="home" ariaLabel="home icon" /> Home
    
  
  
    
      <Icon library="fa" name="folder" ariaLabel="category icon" /> Category
    
  
  
    
      <Icon library="fa" name="file" ariaLabel="item icon" /> Item
    
  
</Breadcrumb>
```

---

### Dot Separator

Set the `separator` prop to `dot` to use dot separators between breadcrumb items. This style is clean and works well for compact navigation.

```tsx live
<Breadcrumb separator="dot">
  
    
      <Icon library="fa" name="home" ariaLabel="home icon" /> Home
    
  
  
    
      <Icon library="fa" name="folder" ariaLabel="category icon" /> Category
    
  
  
    
      <Icon library="fa" name="file" ariaLabel="item icon" /> Item
    
  
</Breadcrumb>
```

---

### Succeeds Separator

Use the `separator` prop with the value `succeeds` to show a chevron-style separator between breadcrumb items. This is another option for visually indicating progression.

```tsx live
<Breadcrumb separator="succeeds">
  
    
      <Icon library="fa" name="home" ariaLabel="home icon" /> Home
    
  
  
    
      <Icon library="fa" name="folder" ariaLabel="category icon" /> Category
    
  
  
    
      <Icon library="fa" name="file" ariaLabel="item icon" /> Item
    
  
</Breadcrumb>
```

---

### Small Size

Set the `size` prop to `small` to render a compact breadcrumb navigation. This is useful for tight layouts or when breadcrumbs are a secondary navigation element.

```tsx live
<Breadcrumb size="small">
  
    
      <Icon library="fa" name="home" ariaLabel="home icon" /> Home
    
  
  
    
      <Icon library="fa" name="folder" ariaLabel="category icon" /> Category
    
  
  
    
      <Icon library="fa" name="file" ariaLabel="item icon" /> Item
    
  
</Breadcrumb>
```

---

### Medium Size

Use the `size` prop with the value `medium` to increase the breadcrumb's size for better visibility or emphasis in your layout.

```tsx live
<Breadcrumb size="medium">
  
    
      <Icon library="fa" name="home" ariaLabel="home icon" /> Home
    
  
  
    
      <Icon library="fa" name="folder" ariaLabel="category icon" /> Category
    
  
  
    
      <Icon library="fa" name="file" ariaLabel="item icon" /> Item
    
  
</Breadcrumb>
```

---

### Large Size

Set the `size` prop to `large` to make the breadcrumb navigation more prominent. This is ideal for main navigation or when breadcrumbs need to stand out.

```tsx live
<Breadcrumb size="large">
  
    
      <Icon library="fa" name="home" ariaLabel="home icon" /> Home
    
  
  
    
      <Icon library="fa" name="folder" ariaLabel="category icon" /> Category
    
  
  
    
      <Icon library="fa" name="file" ariaLabel="item icon" /> Item
    
  
</Breadcrumb>
```

---

### With Icons, Alignment, Separator, Size, and Text Weight

Combine multiple props such as `alignment`, `separator`, `size`, and `textWeight` to fully customize the breadcrumb's appearance. You can also use the `textColor` and `size` props on the `Icon` component for even more control over the look of each breadcrumb item.

```tsx live
<Breadcrumb
  alignment="centered"
  separator="dot"
  size="medium"
  textWeight="semibold"
>
  
    
      <Icon
        library="fa"
        name="home"
        textColor="primary"
        size="small"
        ariaLabel="home icon"
      />{' '}
      Home
    
  
  
    
      <Icon
        library="fa"
        name="folder"
        textColor="info"
        size="small"
        ariaLabel="category icon"
      />{' '}
      Category
    
  
  
    
      <Icon
        library="fa"
        name="file"
        textColor="success"
        size="small"
        ariaLabel="item icon"
      />{' '}
      Item
    
  
</Breadcrumb>
```

---

## Accessibility

- The root is a `<nav class="breadcrumb">` with `aria-label="breadcrumbs"`.
- Each breadcrumb item should be an `` with an `` or ``, and the final active item should have the `is-active` class.

---

## Related Components

- [`Icon`](../elements/icon.md): For adding icons to breadcrumb items.
- [Helper Props](../helpers/usebulmaclasses.md)

---

## Additional Resources

- [Bulma Breadcrumb Documentation](https://bulma.io/documentation/components/breadcrumb/)
- [Storybook: Breadcrumb Stories](https://bestax.io/storybook/?path=/story/components-breadcrumb--default)

---

## Card


## Overview

The `Card` component renders a Bulma-styled card with optional header, image, content, and footer. It supports custom colors, shadows, spacing, alignment, and more for flexible, attractive UI blocks.

---

## Import

```tsx

```

---

## Props

| Prop             | Type                                                                                                                                                                                                                                                                                     | Description                                                       |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `className`      | `string`                                                                                                                                                                                                                                                                                 | Additional CSS classes to apply.                                  |
| `textColor`      | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | Text color for the card.                                          |
| `color`          | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`                                                                                                                                                                                                                    | Bulma color modifier for the card.                                |
| `bgColor`        | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | Background color for the card.                                    |
| `hasShadow`      | `boolean`                                                                                                                                                                                                                                                                                | Whether the card has a shadow (default: `true`).                  |
| `header`         | `React.ReactNode`                                                                                                                                                                                                                                                                        | Card header content, rendered inside `.card-header-title`.        |
| `headerCentered` | `boolean`                                                                                                                                                                                                                                                                                | If true, centers the header title.                                |
| `headerIcon`     | `React.ReactNode`                                                                                                                                                                                                                                                                        | Card header icon, rendered as a sibling to the header title.      |
| `footer`         | `React.ReactNode \| React.ReactNode[]`                                                                                                                                                                                                                                                   | Card footer content; each item is wrapped in `.card-footer-item`. |
| `image`          | `React.ReactNode \| string`                                                                                                                                                                                                                                                              | Card image node or image src string.                              |
| `imageAlt`       | `string`                                                                                                                                                                                                                                                                                 | Alternate text for the card image.                                |
| `children`       | `React.ReactNode`                                                                                                                                                                                                                                                                        | Card content (body).                                              |
| `m`/`p`          | `string`                                                                                                                                                                                                                                                                                 | Bulma margin/padding helper props (e.g. `'4'`, `'auto'`).         |
| `textAlign`      | `'centered' \| 'justified' \| 'left' \| 'right'`                                                                                                                                                                                                                                         | Text alignment.                                                   |
| ...              | All Bulma and standard HTML props                                                                                                                                                                                                                                                        | (See [Helper Props](../helpers/usebulmaclasses))                  |

---

## Usage

### Default Card (Header, Image, Content, Footer)

To create a flexible content block, use the `Card` component with optional `header`, `image`, `children` (for the main content), and `footer` props. This structure is ideal for displaying grouped information, media, or actions in a visually distinct container. You can further customize the card using props like `color`, `bgColor`, `textColor`, `hasShadow`, and Bulma helper props for spacing and alignment.

```tsx live
<Card
  header="Card Header"
  image="https://images.unsplash.com/photo-1506744038136-46273834b3fb?auto=format&fit=crop&w=600&q=80"
  imageAlt="Beautiful forest"
  footer={[
    <Card.FooterItem key="save">Save</Card.FooterItem>,
    <Card.FooterItem key="cancel">Cancel</Card.FooterItem>,
  ]}
>
  Card content goes here.
</Card>
```

---

### With Header Only

Use the `header` prop to display a card with only a header section. This is useful for simple announcements or titles without additional content or actions. The header text appears in the card's top area, styled according to Bulma's card-header.

```tsx live
<Card header="Card Header">
  Quando in rerum natura cursu fit ut populus aliquis inter nationes terrae...
</Card>
```

---

### With Footer Only

Provide the `footer` prop to render a card with only a footer section. Each footer item is wrapped in `.card-footer-item`, making it ideal for action links or summary information at the bottom of the card.

```tsx live
<Card
  footer={[
    <Card.FooterItem key="save">Save</Card.FooterItem>,
    <Card.FooterItem key="cancel">Cancel</Card.FooterItem>,
  ]}
>
  Quando in rerum natura cursu fit ut populus aliquis inter nationes terrae...
</Card>
```

---

### With Image Only

Set the `image` and `imageAlt` props to display a card with only an image. This is useful for gallery layouts or when you want to showcase a visual without additional content or actions.

```tsx live
<Card
  image="https://images.unsplash.com/photo-1506744038136-46273834b3fb?auto=format&fit=crop&w=600&q=80"
  imageAlt="Beautiful forest"
/>
```

---

### With Image and Content

Combine the `image`, `imageAlt`, and `children` props to display a card with an image and content. This is a common pattern for media cards, product listings, or blog previews.

```tsx live
<Card
  image="https://images.unsplash.com/photo-1506744038136-46273834b3fb?auto=format&fit=crop&w=600&q=80"
  imageAlt="Beautiful forest"
>
  Quando in rerum natura cursu fit ut populus aliquis inter nationes terrae...
</Card>
```

---

### No Shadow

Set `hasShadow={false}` to remove the default card shadow. This creates a flatter, more minimal appearance, which can be useful for embedded or secondary cards.

```tsx live
<Card hasShadow={false}>
  Quando in rerum natura cursu fit ut populus aliquis inter nationes terrae...
</Card>
```

---

### Spaced (Margin and Padding)

Use Bulma helper props like `m` (margin) and `p` (padding) to control the card's spacing. For example, `m="4"` and `p="4"` add margin and padding of 4 units, respectively, for better separation and layout control.

```tsx live
<Card m="4" p="4">
  Quando in rerum natura cursu fit ut populus aliquis inter nationes terrae...
</Card>
```

---

### Viewport Specific (Text Color on Tablet)

Apply the `textColor` prop with a value like `primary` and the `viewport` prop set to `tablet` to change the card's text color only on tablet screens. This enables responsive design adjustments for different devices.

```tsx live
<Card textColor="primary" viewport="tablet">
  Quando in rerum natura cursu fit ut populus aliquis inter nationes terrae...
</Card>
```

---

### Interactive (Colors, Spacing, Alignment, Footer)

Combine multiple props such as `header`, `textColor`, `bgColor`, `m`, `p`, `textAlign`, `hasShadow`, and `footer` to create a highly interactive and visually distinct card. This pattern is ideal for call-to-action cards, dashboards, or feature highlights.

```tsx live
<Card
  header="Upgrade to Pro"
  headerIcon={
    <button className="card-header-icon">
      <Icon library="fa" name="bolt" textColor="warning" ariaLabel="Pro" />
    </button>
  }
  image="https://images.unsplash.com/photo-1551288049-bebda4e38f71?auto=format&fit=crop&w=600&q=80"
  imageAlt="Dashboard analytics"
  m="3"
  textAlign="centered"
  hasShadow
  footer={[
    <Button key="upgrade" color="success">
      Upgrade Now
    </Button>,
    <Button key="learn" color="info" isOutlined>
      Learn More
    </Button>,
  ]}
>
  Unlock advanced analytics, priority support, and unlimited exports for your
  team.
</Card>
```

---

## Compound Components

The `Card` component also supports a compound component API for maximum flexibility. This allows you to compose cards with fine-grained control over each section.

### Card.Header

Renders the card header section with proper styling. When used without `Card.Header.Title`, it automatically wraps content in a `.card-header-title` div. When used with `Card.Header.Title`, it renders the title component directly without additional wrapping.

**Props:**

- `className?`: Additional CSS classes
- `centered?`: Whether to center the header content (only applies when not using `Card.Header.Title`)
- All standard HTML attributes for `<header>`

### Card.Header.Title

Renders the card header title with proper styling. This provides more granular control over the header title when using compound components. When used inside `Card.Header`, it prevents automatic wrapping.

**Props:**

- `className?`: Additional CSS classes
- `centered?`: Whether to center the header title
- All standard HTML attributes for ``

### Card.Header.Icon

Renders the card header icon button with proper styling. This is typically placed after `Card.Header.Title` for actions like expand/collapse or accessing more options.

**Props:**

- `className?`: Additional CSS classes
- `aria-label?`: Accessibility label (defaults to "more options")
- All standard HTML attributes for `<button>`

### Card.Image

Renders the card image section.

**Props:**

- `className?`: Additional CSS classes
- All standard HTML attributes for ``

### Card.Content

Renders the main card content section.

**Props:**

- `className?`: Additional CSS classes
- All standard HTML attributes for ``

### Card.Footer

Renders the card footer section.

**Props:**

- `className?`: Additional CSS classes
- All standard HTML attributes for `<footer>`

### Card.FooterItem

Renders individual footer items with proper styling.

**Props:**

- `className?`: Additional CSS classes
- All standard HTML attributes for ``

### Compound Component Examples

#### Complete Card with Compound Components

```tsx live

<Card>
  <Card.Header>
    <Card.Header.Title>Compound Component Card</Card.Header.Title>
    <Card.Header.Icon aria-label="more options">
      <Icon name="angle-down" variant="solid" ariaLabel="expand" />
    </Card.Header.Icon>
  </Card.Header>
  <Card.Image>
    <Image
      src="https://images.unsplash.com/photo-1506744038136-46273834b3fb?auto=format&fit=crop&w=600&q=80"
      alt="Beautiful forest"
      size="4by3"
    />
  </Card.Image>
  <Card.Content>
    <Content>
      This card is built using compound components for maximum flexibility.
    </Content>
  </Card.Content>
  <Card.Footer>
    <Card.FooterItem>
      <Button color="primary">Save</Button>
    </Card.FooterItem>
    <Card.FooterItem>
      <Button>Cancel</Button>
    </Card.FooterItem>
  </Card.Footer>
</Card>;
```

#### Minimal Compound Card

```tsx live
<Card>
  <Card.Header>
    <Card.Header.Title>Simple Header</Card.Header.Title>
  </Card.Header>
  <Card.Content>
    <Paragraph>Just some minimal content using compound components.</Paragraph>
  </Card.Content>
</Card>
```

#### Card Header with Icon

```tsx live
function ExpandableCard() {
  const [isOpen, setIsOpen] = React.useState(true);

  return (
    <Card>
      <Card.Header>
        <Card.Header.Title>Expandable Card</Card.Header.Title>
        <Card.Header.Icon
          aria-label={isOpen ? 'collapse' : 'expand'}
          onClick={() => setIsOpen(!isOpen)}
        >
          <Icon
            library="fa"
            name={isOpen ? 'angle-up' : 'angle-down'}
            ariaLabel={isOpen ? 'collapse' : 'expand'}
          />
        </Card.Header.Icon>
      </Card.Header>
      {isOpen && (
        <Card.Content>
          This card uses React state to toggle content visibility. Click the
          icon in the header to expand or collapse this section.
        </Card.Content>
      )}
    </Card>
  );
}
```

#### Mixed Approach

You can combine the traditional prop-based API with compound components:

```tsx live
<Card header="Prop-based header" textColor="primary" m="3">
  <Card.Content bgColor="light">
    <Paragraph>
      You can mix prop-based and compound component approaches!
    </Paragraph>
  </Card.Content>
  <Card.Footer>
    <Card.FooterItem>Mixed approach example</Card.FooterItem>
  </Card.Footer>
</Card>
```

---

## Accessibility

- The card image uses an `alt` attribute for screen readers.
- Use semantic content for the header, body, and footer as needed.

---

## Related Components

- [`Icon`](../elements/icon.md): For icons in card headers and content.
- [`Image`](../elements/image.md): For responsive card images with proper aspect ratios.
- [Helper Props](../helpers/usebulmaclasses.md) for spacing, color, and alignment utilities.
- [Bulma Card Documentation](https://bulma.io/documentation/components/card/)

---

## Additional Resources

- [Storybook: Card Stories](https://bestax.io/storybook/?path=/story/components-card--default)

---

## Carousel


## Overview

The `Carousel` component provides an image/content slider with navigation arrows and indicators. It supports auto-play, drag navigation, and customizable styles.

---

## Import

```tsx

```

---

## Props

### Carousel

| Prop                | Type                                                                       | Default    | Description                                                                             |
| ------------------- | -------------------------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------- |
| `value`             | `number`                                                                   | `0`        | Current active slide index (controlled).                                                |
| `autoplay`          | `boolean`                                                                  | `false`    | Enable auto-play.                                                                       |
| `interval`          | `number`                                                                   | `5000`     | Auto-play interval in milliseconds.                                                     |
| `pauseOnHover`      | `boolean`                                                                  | `true`     | Pause auto-play on hover.                                                               |
| `repeat`            | `boolean`                                                                  | `true`     | Loop back to first slide after last.                                                    |
| `hasDrag`           | `boolean`                                                                  | `true`     | Enable drag/swipe navigation.                                                           |
| `arrow`             | `boolean`                                                                  | `true`     | Show navigation arrows.                                                                 |
| `arrowHover`        | `boolean`                                                                  | `false`    | Only show arrows on hover.                                                              |
| `arrowBackground`   | `boolean`                                                                  | `true`     | Show semi-transparent background on arrow buttons. Set to `false` for icon-only arrows. |
| `iconPrev`          | `string`                                                                   | —          | Icon name for the previous arrow button.                                                |
| `iconNext`          | `string`                                                                   | —          | Icon name for the next arrow button.                                                    |
| `iconLibrary`       | `'fa'` \| `'mdi'` \| `'ion'` \| `'material-icons'` \| `'material-symbols'` | —          | Icon library to use.                                                                    |
| `iconVariant`       | `string`                                                                   | —          | Icon style variant (e.g., 'solid', 'outlined').                                         |
| `iconSize`          | `'small'` \| `'medium'` \| `'large'`                                       | —          | Icon size modifier.                                                                     |
| `iconFeatures`      | `string \| string[]`                                                       | —          | Additional icon modifiers.                                                              |
| `indicator`         | `boolean`                                                                  | `true`     | Show slide indicators.                                                                  |
| `indicatorInside`   | `boolean`                                                                  | `false`    | Position indicators inside carousel.                                                    |
| `indicatorPosition` | `'bottom'` \| `'top'`                                                      | `'bottom'` | Indicator position.                                                                     |
| `indicatorStyle`    | `'circles'` \| `'dots'` \| `'lines'` \| `'bars'`                           | `'dots'`   | Indicator style.                                                                        |
| `onChange`          | `(value: number) => void`                                                  | —          | Callback when slide changes.                                                            |
| `children`          | `React.ReactNode`                                                          | —          | CarouselItem children.                                                                  |
| `className`         | `string`                                                                   | —          | Additional CSS classes.                                                                 |
| `ref`               | `React.Ref<HTMLElement>`                                                   | —          | Ref forwarded to the carousel element.                                                  |
| `arrowColor`        | `'light'` \| `'dark'`                                                      | —          | Color theme for navigation arrows.                                                      |
| ...                 | All standard HTML and Bulma helper props                                   |            | (See [Helper Props](../helpers/usebulmaclasses))                                        |

### CarouselItem

| Prop        | Type      | Default | Description                                      |
| ----------- | --------- | ------- | ------------------------------------------------ |
| `active`    | `boolean` | —       | Whether this item is active (set automatically). |
| `className` | `string`  | —       | Additional CSS classes.                          |

---

## Usage

### Basic Carousel

A simple carousel with colored slides using the Hero component.

```tsx live
<Carousel indicatorStyle="dots">
  <CarouselItem>
    <Hero color="primary" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Slide 1</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="success" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Slide 2</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="danger" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Slide 3</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
</Carousel>
```

---

### Auto-playing Carousel

Carousel that automatically advances slides.

```tsx live
<Carousel autoplay interval={3000}>
  <CarouselItem>
    <Hero color="info" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Info</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="warning" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Warning</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="success" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Success</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
</Carousel>
```

---

### Indicator Styles

Different indicator style options.

```tsx live
function IndicatorExample() {
  const [style, setStyle] = useState('dots');
  return (
    <Block>
      <Buttons mb="4">
        <Button
          onClick={() => setStyle('dots')}
          color={style === 'dots' ? 'primary' : undefined}
        >
          Dots
        </Button>
        <Button
          onClick={() => setStyle('circles')}
          color={style === 'circles' ? 'primary' : undefined}
        >
          Circles
        </Button>
        <Button
          onClick={() => setStyle('lines')}
          color={style === 'lines' ? 'primary' : undefined}
        >
          Lines
        </Button>
        <Button
          onClick={() => setStyle('bars')}
          color={style === 'bars' ? 'primary' : undefined}
        >
          Bars
        </Button>
      </Buttons>
      <Carousel indicatorStyle={style}>
        <CarouselItem>
          <Hero color="primary" size="medium">
            <Hero.Body textAlign="centered">
              <Paragraph textColor="white">Slide 1</Paragraph>
            </Hero.Body>
          </Hero>
        </CarouselItem>
        <CarouselItem>
          <Hero color="success" size="medium">
            <Hero.Body textAlign="centered">
              <Paragraph textColor="white">Slide 2</Paragraph>
            </Hero.Body>
          </Hero>
        </CarouselItem>
        <CarouselItem>
          <Hero color="danger" size="medium">
            <Hero.Body textAlign="centered">
              <Paragraph textColor="white">Slide 3</Paragraph>
            </Hero.Body>
          </Hero>
        </CarouselItem>
      </Carousel>
    </Block>
  );
}
```

---

### Without Arrows

Carousel with indicators only.

```tsx live
<Carousel arrow={false}>
  <CarouselItem>
    <Hero color="primary" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Swipe or Click Dots</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="link" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Navigation Only</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
</Carousel>
```

---

### Arrows on Hover

Show arrows only when hovering over the carousel.

```tsx live
<Carousel arrowHover>
  <CarouselItem>
    <Hero color="dark" size="medium">
      <Hero.Body textAlign="centered">
        <Paragraph textColor="white">Hover to see arrows</Paragraph>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="primary" size="medium">
      <Hero.Body textAlign="centered">
        <Paragraph textColor="white">Slide 2</Paragraph>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="success" size="medium">
      <Hero.Body textAlign="centered">
        <Paragraph textColor="white">Slide 3</Paragraph>
      </Hero.Body>
    </Hero>
  </CarouselItem>
</Carousel>
```

---

### Transparent Arrow Buttons

Remove the arrow button backgrounds to show just the icons.

```tsx live
<Carousel arrowBackground={false}>
  <CarouselItem>
    <Hero color="primary" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Slide 1</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="success" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Slide 2</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="danger" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Slide 3</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
</Carousel>
```

---

### Custom Arrow Icons

Customize navigation arrows using the icon props. The Carousel uses the Icon component internally.

```tsx live
<Carousel
  iconPrev="chevron-left"
  iconNext="chevron-right"
  iconLibrary="fa"
  iconVariant="solid"
>
  <CarouselItem>
    <Hero color="primary" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Slide 1</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="success" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Slide 2</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="danger" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Slide 3</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
</Carousel>
```

### With Material Design Icons

```tsx live
<Carousel iconPrev="arrow-left" iconNext="arrow-right" iconLibrary="mdi">
  <CarouselItem>
    <Hero color="primary" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Slide 1</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="success" size="medium">
      <Hero.Body textAlign="centered">
        <Title as="p">Slide 2</Title>
      </Hero.Body>
    </Hero>
  </CarouselItem>
</Carousel>
```

:::tip Icon Libraries
The icon props follow the same naming as the [Icon component](../elements/icon.md). See [Alternative Icon Libraries](../../guides/getting-started/alternative-icons.md) for setup instructions.
:::

---

### Controlled Carousel

Externally controlled carousel with custom navigation.

```tsx live
function ControlledExample() {
  const [currentSlide, setCurrentSlide] = useState(0);
  return (
    <Block>
      <Buttons mb="4">
        <Button
          onClick={() => setCurrentSlide(0)}
          color={currentSlide === 0 ? 'primary' : undefined}
        >
          1
        </Button>
        <Button
          onClick={() => setCurrentSlide(1)}
          color={currentSlide === 1 ? 'primary' : undefined}
        >
          2
        </Button>
        <Button
          onClick={() => setCurrentSlide(2)}
          color={currentSlide === 2 ? 'primary' : undefined}
        >
          3
        </Button>
      </Buttons>
      <Carousel
        value={currentSlide}
        onChange={setCurrentSlide}
        indicator={false}
      >
        <CarouselItem>
          <Hero color="primary" size="medium">
            <Hero.Body textAlign="centered">
              <Paragraph textColor="white">Slide 1</Paragraph>
            </Hero.Body>
          </Hero>
        </CarouselItem>
        <CarouselItem>
          <Hero color="success" size="medium">
            <Hero.Body textAlign="centered">
              <Paragraph textColor="white">Slide 2</Paragraph>
            </Hero.Body>
          </Hero>
        </CarouselItem>
        <CarouselItem>
          <Hero color="danger" size="medium">
            <Hero.Body textAlign="centered">
              <Paragraph textColor="white">Slide 3</Paragraph>
            </Hero.Body>
          </Hero>
        </CarouselItem>
      </Carousel>
      <Paragraph mt="2">Current slide: {currentSlide + 1}</Paragraph>
    </Block>
  );
}
```

---

### Non-repeating Carousel

Carousel that stops at the first and last slides.

```tsx live
<Carousel repeat={false}>
  <CarouselItem>
    <Hero color="danger" size="medium">
      <Hero.Body textAlign="centered">
        <Paragraph textColor="white">First (no previous)</Paragraph>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="warning" size="medium">
      <Hero.Body textAlign="centered">
        <Paragraph>Middle slide</Paragraph>
      </Hero.Body>
    </Hero>
  </CarouselItem>
  <CarouselItem>
    <Hero color="success" size="medium">
      <Hero.Body textAlign="centered">
        <Paragraph textColor="white">Last (no next)</Paragraph>
      </Hero.Body>
    </Hero>
  </CarouselItem>
</Carousel>
```

---

## Accessibility

- Uses `role="region"` with `aria-roledescription="carousel"`
- Navigation arrows have `aria-label` for screen readers
- Indicators use `role="tablist"` and `role="tab"` semantics
- Keyboard navigation with arrow keys when focused
- Previous/Next buttons are properly disabled at boundaries when not repeating

---

## Related Components

- [Modal](./modal.md) - For displaying content in an overlay
- [Tabs](./tabs.md) - For tabbed content navigation

---

## Additional Resources

- [Storybook: Carousel Stories](https://bestax.io/storybook/?path=/story/components-carousel)

:::tip Pro Tip
Use the `pauseOnHover` prop (enabled by default) to let users interact with carousel content without it auto-advancing.
:::

---

## Collapse


## Overview

The `Collapse` component provides an expandable/collapsible content panel. It's perfect for accordions, FAQs, settings panels, and any content that should be hidden by default. Supports both controlled and uncontrolled modes, with smooth animations and full accessibility support.

---

## Import

```tsx

```

---

## Props

| Prop               | Type                                     | Default  | Description                                      |
| ------------------ | ---------------------------------------- | -------- | ------------------------------------------------ |
| `open`             | `boolean`                                | —        | Controlled open state.                           |
| `defaultOpen`      | `boolean`                                | `false`  | Initial open state for uncontrolled usage.       |
| `onOpen`           | `() => void`                             | —        | Callback when collapse opens.                    |
| `onClose`          | `() => void`                             | —        | Callback when collapse closes.                   |
| `trigger`          | `React.ReactNode`                        | —        | The clickable trigger element (header/button).   |
| `animation`        | `'fade'` \| `'slide'` \| `false`         | `'fade'` | Animation style, or `false` to disable.          |
| `ariaId`           | `string`                                 | auto     | Custom aria id for accessibility.                |
| `children`         | `React.ReactNode`                        | —        | The collapsible content.                         |
| `className`        | `string`                                 | —        | Additional CSS classes.                          |
| `triggerClassName` | `string`                                 | —        | Additional classes for the trigger wrapper.      |
| `contentClassName` | `string`                                 | —        | Additional classes for the content wrapper.      |
| `position`         | `'top'` \| `'bottom'`                    | `'top'`  | Position of the trigger relative to content.     |
| `bordered`         | `boolean`                                | —        | Adds a border around the collapse.               |
| ...                | All standard HTML and Bulma helper props |          | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Basic Collapse

A simple uncontrolled collapse.

```tsx live
function example() {
  return (
    <Collapse
      trigger={
        <Block
          p="3"
          bgColor="white-ter"
          cursor="pointer"
          style={{ borderRadius: '4px' }}
        >
          Click to expand
        </Block>
      }
    >
      <Block p="3">
        <Paragraph>
          This is the collapsible content. It can contain any React elements.
        </Paragraph>
        <Paragraph>Click the header again to collapse.</Paragraph>
      </Block>
    </Collapse>
  );
}
```

---

### Default Open

Collapse that starts open by default.

```tsx live
function example() {
  return (
    <Collapse
      defaultOpen
      trigger={
        <Block
          p="3"
          bgColor="white-ter"
          cursor="pointer"
          style={{ borderRadius: '4px' }}
        >
          This starts open
        </Block>
      }
    >
      <Block p="3">
        <Paragraph>This content is visible by default.</Paragraph>
      </Block>
    </Collapse>
  );
}
```

---

### Without Animation

Collapse that toggles instantly without animation.

```tsx live
function example() {
  return (
    <Collapse
      animation={false}
      trigger={
        <Block
          p="3"
          bgColor="white-ter"
          cursor="pointer"
          style={{ borderRadius: '4px' }}
        >
          No animation
        </Block>
      }
    >
      <Block p="3">
        <Paragraph>This collapse has animation disabled.</Paragraph>
      </Block>
    </Collapse>
  );
}
```

---

### Controlled Mode

Collapse with external state management.

```tsx live
function example() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <Block>
      <Block mb="4">
        <Button color="primary" onClick={() => setIsOpen(!isOpen)}>
          {isOpen ? 'Close' : 'Open'} Collapse
        </Button>
        State: {isOpen ? 'Open' : 'Closed'}
      </Block>
      <Collapse
        open={isOpen}
        trigger={
          <Block p="3" bgColor="white-ter" style={{ borderRadius: '4px' }}>
            Controlled collapse (use button above)
          </Block>
        }
      >
        <Block p="3">
          <Paragraph>This collapse is controlled by external state.</Paragraph>
        </Block>
      </Collapse>
    </Block>
  );
}
```

---

### Accordion

Multiple collapses working together as an accordion.

```tsx live
function example() {
  const [openIndex, setOpenIndex] = useState(0);

  const items = [
    { title: 'Section 1', content: 'Content for section 1.' },
    { title: 'Section 2', content: 'Content for section 2.' },
    { title: 'Section 3', content: 'Content for section 3.' },
  ];

  return (
    <Block display="flex" flexDirection="column" gap="2">
      {items.map((item, index) => (
        <Collapse
          key={index}
          className="collapse is-bordered"
          open={openIndex === index}
          trigger={
            <Block
              p="4"
              onClick={() => setOpenIndex(openIndex === index ? -1 : index)}
              display="flex"
              justifyContent="space-between"
              alignItems="center"
            >
              {item.title}
              {openIndex === index ? '−' : '+'}
            </Block>
          }
        >
          <Paragraph p="4">{item.content}</Paragraph>
        </Collapse>
      ))}
    </Block>
  );
}
```

---

### Card Style

Collapse with card styling.

```tsx live
function example() {
  return (
    <Collapse
      className="collapse is-card"
      defaultOpen
      trigger={
        <Block className="collapse-trigger-header">
          Card Collapse
          <Icon name="fas fa-chevron-down" />
        </Block>
      }
    >
      <Paragraph>
        This collapse is styled like a card with shadow and padding.
      </Paragraph>
      <Paragraph>Perfect for FAQ sections or settings panels.</Paragraph>
    </Collapse>
  );
}
```

---

### FAQ Example

A common FAQ pattern with multiple collapses.

```tsx live
function example() {
  const faqs = [
    {
      q: 'What is Bestax?',
      a: 'Bestax is a React component library built on Bulma.',
    },
    { q: 'How do I install it?', a: 'pnpm add @allxsmith/bestax-bulma' },
    { q: 'Is it free?', a: 'Yes, Bestax is open source and free to use.' },
  ];

  const [openStates, setOpenStates] = useState(faqs.map(() => false));

  const toggle = index => {
    setOpenStates(prev =>
      prev.map((state, i) => (i === index ? !state : state))
    );
  };

  return (
    <Block>
      <Title size="5" mb="4">
        FAQ
      </Title>
      <Block display="flex" flexDirection="column" gap="2">
        {faqs.map((faq, index) => (
          <Collapse
            key={index}
            className="collapse is-bordered"
            trigger={
              <Block
                p="4"
                onClick={() => toggle(index)}
                display="flex"
                justifyContent="space-between"
              >
                {faq.q}
                {openStates[index] ? '▲' : '▼'}
              </Block>
            }
            open={openStates[index]}
          >
            <Paragraph p="4" textColor="grey-dark">
              {faq.a}
            </Paragraph>
          </Collapse>
        ))}
      </Block>
    </Block>
  );
}
```

---

## CSS Classes

The Collapse component supports these additional CSS classes:

| Class         | Description                         |
| ------------- | ----------------------------------- |
| `is-active`   | Applied when the collapse is open   |
| `is-card`     | Card-style with shadow and padding  |
| `is-bordered` | Bordered style with rounded corners |

---

## Accessibility

- Trigger has `role="button"` and `tabIndex="0"` for keyboard access
- Trigger has `aria-expanded` to indicate open/closed state
- Trigger has `aria-controls` pointing to the content element
- Content has `aria-hidden` matching the collapsed state
- Supports keyboard navigation (Enter and Space to toggle)

---

## Related

- [Tabs](./tabs.md) - Tabbed content panels
- [Panel](./panel.md) - Bulma panel component

---

## Dialog


## Overview

The `Dialog` component provides confirmation and alert dialogs with customizable actions. Dialogs are modal and require user interaction before they can be dismissed.

---

## Import

```tsx

```

---

## Props

| Prop          | Type                                                                | Default     | Description                                          |
| ------------- | ------------------------------------------------------------------- | ----------- | ---------------------------------------------------- |
| `isOpen`      | `boolean`                                                           | —           | Whether the dialog is open (required).               |
| `title`       | `string`                                                            | —           | Dialog title.                                        |
| `message`     | `string` \| `React.ReactNode`                                       | —           | Dialog message/content (required).                   |
| `type`        | `'default'` \| `'success'` \| `'danger'` \| `'warning'` \| `'info'` | `'default'` | Type/color of the dialog.                            |
| `confirmText` | `string`                                                            | `'OK'`      | Text for confirm button.                             |
| `cancelText`  | `string`                                                            | `'Cancel'`  | Text for cancel button.                              |
| `onConfirm`   | `() => void`                                                        | —           | Callback when confirm button is clicked.             |
| `onCancel`    | `() => void`                                                        | —           | Callback when cancel button is clicked or dismissed. |
| `showCancel`  | `boolean`                                                           | `true`      | Whether to show cancel button.                       |
| `canCancel`   | `boolean`                                                           | `true`      | Whether the dialog can be dismissed.                 |
| `focusCancel` | `boolean`                                                           | `false`     | Focus cancel button instead of confirm.              |
| `icon`        | `React.ReactNode`                                                   | —           | Custom icon to display.                              |
| `className`   | `string`                                                            | —           | Additional CSS classes.                              |
| `ref`         | `React.Ref<HTMLElement>`                                            | —           | Ref forwarded to the dialog element.                 |
| ...           | All standard HTML and Bulma helper props                            |             | (See [Helper Props](../helpers/usebulmaclasses))     |

---

## Usage

### Alert Dialog

A simple alert dialog with only a confirm button.

```tsx live
function example() {
  const [showDialog, setShowDialog] = useState(false);
  return (
    <Block>
      <Button color="info" onClick={() => setShowDialog(true)}>
        Show Alert
      </Button>
      <Dialog
        isOpen={showDialog}
        title="Information"
        message="Your changes have been saved successfully."
        type="success"
        showCancel={false}
        onConfirm={() => setShowDialog(false)}
      />
    </Block>
  );
}
```

---

### Confirm Dialog

A confirmation dialog with both confirm and cancel options.

```tsx live
function example() {
  const [showDialog, setShowDialog] = useState(false);
  const [result, setResult] = useState('');

  return (
    <Block>
      <Button color="danger" onClick={() => setShowDialog(true)}>
        Delete Item
      </Button>
      <Paragraph mt="2">Result: {result}</Paragraph>
      <Dialog
        isOpen={showDialog}
        title="Delete Item?"
        message="This action cannot be undone. Are you sure you want to delete this item?"
        type="danger"
        confirmText="Delete"
        onConfirm={() => {
          setResult('Deleted');
          setShowDialog(false);
        }}
        onCancel={() => {
          setResult('Cancelled');
          setShowDialog(false);
        }}
      />
    </Block>
  );
}
```

---

### Dialog Types

Different dialog types with matching icons.

```tsx live
function example() {
  const [dialogType, setDialogType] = useState(null);
  return (
    <Block>
      <Buttons>
        <Button color="success" onClick={() => setDialogType('success')}>
          Success
        </Button>
        <Button color="danger" onClick={() => setDialogType('danger')}>
          Danger
        </Button>
        <Button color="warning" onClick={() => setDialogType('warning')}>
          Warning
        </Button>
        <Button color="info" onClick={() => setDialogType('info')}>
          Info
        </Button>
      </Buttons>
      {dialogType && (
        <Dialog
          isOpen
          title={`${dialogType.charAt(0).toUpperCase() + dialogType.slice(1)} Dialog`}
          message={`This is a ${dialogType} dialog with an automatic icon.`}
          type={dialogType}
          onConfirm={() => setDialogType(null)}
          onCancel={() => setDialogType(null)}
        />
      )}
    </Block>
  );
}
```

---

### With Rich Content

Dialog with custom React content.

```tsx live
function example() {
  const [showDialog, setShowDialog] = useState(false);
  return (
    <Block>
      <Button onClick={() => setShowDialog(true)}>Show Terms</Button>
      <Dialog
        isOpen={showDialog}
        title="Terms of Service"
        message={
          <Block>
            <Paragraph mb="2">By clicking "Accept", you agree to:</Paragraph>
            
              Our terms of service
              Our privacy policy
              Receive email notifications
            
          </Block>
        }
        confirmText="Accept"
        cancelText="Decline"
        onConfirm={() => setShowDialog(false)}
        onCancel={() => setShowDialog(false)}
      />
    </Block>
  );
}
```

---

### Non-cancelable Dialog

A dialog that must be confirmed (cannot be dismissed by clicking outside or pressing Escape).

```tsx live
function example() {
  const [showDialog, setShowDialog] = useState(false);
  return (
    <Block>
      <Button color="warning" onClick={() => setShowDialog(true)}>
        Show Required Action
      </Button>
      <Dialog
        isOpen={showDialog}
        title="Required Action"
        message="You must complete this action to continue."
        type="warning"
        canCancel={false}
        showCancel={false}
        confirmText="I Understand"
        onConfirm={() => setShowDialog(false)}
      />
    </Block>
  );
}
```

---

## Programmatic API

For showing dialogs from anywhere in your app, use the programmatic API.

### Setup

Add the `DialogContainer` once at your app root:

```tsx title="src/App.tsx"

function App() {
  return (
    <>
      <YourRoutes />
      <DialogContainer />
    </>
  );
}
```

### Programmatic Alert

```tsx live
function example() {
  return (
    <Block>
      <DialogContainer />
      <Buttons>
        <Button
          color="info"
          onClick={() => dialog.alert('Something happened!')}
        >
          Simple Alert
        </Button>
        <Button
          color="success"
          onClick={() =>
            dialog.alert({
              title: 'Success',
              message: 'Operation completed!',
              type: 'success',
            })
          }
        >
          Success Alert
        </Button>
      </Buttons>
    </Block>
  );
}
```

### Programmatic Confirm

```tsx live
function example() {
  const [result, setResult] = useState('');

  return (
    <Block>
      <DialogContainer />
      <Button
        color="danger"
        onClick={async () => {
          const confirmed = await dialog.confirm({
            title: 'Delete Item?',
            message: 'This action cannot be undone.',
            type: 'danger',
            confirmText: 'Delete',
          });
          setResult(confirmed ? 'Item deleted!' : 'Cancelled.');
        }}
      >
        Delete Item
      </Button>
      {result && <Paragraph mt="3">{result}</Paragraph>}
    </Block>
  );
}
```

### Chained Dialogs

```tsx live
function example() {
  return (
    <Block>
      <DialogContainer />
      <Button
        color="warning"
        onClick={async () => {
          const confirmed = await dialog.confirm({
            title: 'Delete Item?',
            message: 'This action cannot be undone.',
            type: 'danger',
            confirmText: 'Delete',
          });
          if (confirmed) {
            await dialog.alert({
              title: 'Deleted',
              message: 'Item was deleted successfully.',
              type: 'success',
            });
          }
        }}
      >
        Delete with Confirmation
      </Button>
    </Block>
  );
}
```

---

## Accessibility

- Uses `role="alertdialog"` for proper screen reader announcement
- Has `aria-modal="true"` to indicate modal behavior
- Focus is trapped within the dialog when open
- Escape key closes the dialog (when `canCancel` is true)
- Body scroll is prevented when dialog is open
- Confirm/cancel buttons are keyboard accessible

---

## Related Components

- [Toast](./toast.md) - For non-blocking notifications with optional action buttons
- [Modal](./modal.md) - For custom modal dialogs

---

## Additional Resources

- [Storybook: Dialog Stories](https://bestax.io/storybook/?path=/story/components-dialog)

:::tip Pro Tip
Use the programmatic `dialog.confirm()` with async/await to create clean, sequential flows without managing dialog state manually.
:::

---

## Dropdown


## Overview

The `Dropdown` component provides Bulma's versatile dropdown menu for your Bulma React UI. It supports custom triggers, menu alignment, hover or click activation, right/up direction, disabled state, controlled/uncontrolled open state, menu dividers, and full Bulma/utility helper props. Use it for navigation menus, actions, or custom pop-up lists.

:::info
Dropdowns can be fully controlled, used as hoverable, or triggered by click. Menu items and dividers are included.
:::

---

## Import

```tsx

```

---

## Props

### Dropdown

| Prop             | Type                        | Default | Description                                      |
| ---------------- | --------------------------- | ------- | ------------------------------------------------ |
| `label`          | `React.ReactNode`           | —       | The dropdown button/trigger content.             |
| `children`       | `React.ReactNode`           | —       | Dropdown menu items and dividers.                |
| `className`      | `string`                    | —       | Additional CSS classes for root.                 |
| `menuClassName`  | `string`                    | —       | Additional CSS classes for the dropdown menu.    |
| `active`         | `boolean`                   | —       | Whether the dropdown is open (controlled).       |
| `up`             | `boolean`                   | false   | Dropdown menu opens upward.                      |
| `right`          | `boolean`                   | false   | Menu is right-aligned.                           |
| `hoverable`      | `boolean`                   | false   | Open on hover instead of click.                  |
| `disabled`       | `boolean`                   | false   | Disables the dropdown trigger.                   |
| `onActiveChange` | `(active: boolean) => void` | —       | Callback when dropdown active state changes.     |
| `closeOnClick`   | `boolean`                   | `true`  | Close dropdown when a menu item is clicked.      |
| `id`             | `string`                    | —       | Root element ID (for aria-controls, etc).        |
| ...              | All Bulma helper props      |         | (See [Helper Props](../helpers/usebulmaclasses)) |

### Dropdown.Item

| Prop        | Type                                     | Default | Description                                      |
| ----------- | ---------------------------------------- | ------- | ------------------------------------------------ |
| `active`    | `boolean`                                | —       | Makes this item appear active.                   |
| `className` | `string`                                 | —       | Additional CSS classes.                          |
| `as`        | `'a'` \| `'div'` \| `'button'`           | `'a'`   | Element type to render.                          |
| `children`  | `React.ReactNode`                        | —       | Content for the menu item.                       |
| ...         | All standard HTML and Bulma helper props |         | (See [Helper Props](../helpers/usebulmaclasses)) |

### Dropdown.Divider

No props. Renders as a menu divider (``).

---

## Usage

### Default Dropdown

To create a dropdown menu, use the `Dropdown` component with a `label` for the trigger and `Dropdown.Item` children for each menu option. You can add a `Dropdown.Divider` to separate groups of items. This pattern is ideal for navigation menus, action lists, or custom pop-up menus in your UI.

```tsx live

function Example() {
  return (
    <Dropdown label="Dropdown Menu">
      <Dropdown.Item>First Item</Dropdown.Item>
      <Dropdown.Item>Second Item</Dropdown.Item>
      <Dropdown.Divider />
      <Dropdown.Item>Third Item</Dropdown.Item>
      <Dropdown.Item>Fourth Item</Dropdown.Item>
      <Dropdown.Item>Fifth Item</Dropdown.Item>
    </Dropdown>
  );
}
```

---

### Custom Tags (button, div, anchor)

Use the `as` prop on `Dropdown.Item` to render different HTML elements, such as `a`, `div`, or `button`. This allows you to customize the behavior and semantics of each dropdown item, supporting links, actions, or custom content.

```tsx live
<Dropdown label="Custom Dropdown Content">
  <Dropdown.Item as="a" href="https://example.com" target="_blank">
    Anchor Item
  </Dropdown.Item>
  <Dropdown.Item as="div">Div Item</Dropdown.Item>
  <Dropdown.Item as="button" onClick={() => alert('Clicked!')}>
    Button Item
  </Dropdown.Item>
</Dropdown>
```

---

### Hoverable and Always Active

Add the `hoverable` prop to open the dropdown on hover, and the `active` prop to keep it always open. This is useful for menus that should remain visible or for previewing dropdown content without a click.

```tsx live
<Dropdown label="Hoverable + Active" hoverable active>
  <Dropdown.Item>Hover or Always Open</Dropdown.Item>
  <Dropdown.Item>Second</Dropdown.Item>
  <Dropdown.Divider />
  <Dropdown.Item>Another</Dropdown.Item>
</Dropdown>
```

---

### Right-Aligned Dropdown

Set the `right` prop to align the dropdown menu to the right edge of its trigger. This is useful for menus in toolbars or when space is limited on the left.

```tsx live
<Dropdown label="Dropdown Right" right>
  <Dropdown.Item>Right 1</Dropdown.Item>
  <Dropdown.Item>Right 2</Dropdown.Item>
</Dropdown>
```

---

### Upward Dropdown

Use the `up` prop to make the dropdown menu open upward instead of downward. This is helpful when the dropdown is near the bottom of the viewport or container.

```tsx live
<Dropdown label="Dropdown Up" up>
  <Dropdown.Item>Up 1</Dropdown.Item>
  <Dropdown.Item>Up 2</Dropdown.Item>
</Dropdown>
```

---

### Controlled Dropdown Example

Control the open/close state of the dropdown by setting the `active` prop and handling state changes with `onActiveChange`. This pattern is useful for advanced interactions or integrating with other UI state.

```tsx live
function example() {
  const [open, setOpen] = useState(false);

  return (
    <Dropdown
      label="Controlled Dropdown"
      active={open}
      onActiveChange={setOpen}
    >
      <Dropdown.Item>Item A</Dropdown.Item>
      <Dropdown.Item>Item B</Dropdown.Item>
    </Dropdown>
  );
}
```

---

## Accessibility

- The dropdown root is a `` with ARIA roles/attributes for menu and trigger.
- The trigger button uses `aria-haspopup`, `aria-controls`, and `aria-expanded`.
- Menu items are focusable and use `role="menuitem"`.
- Clicking outside closes the dropdown in most cases.

:::note
For custom keyboard navigation or focus management, add handlers as needed.
:::

---

## Related Components

- [`Button`](../elements/button.md): Use Bulma/Bestax buttons as triggers if needed.
- [Helper Props](../helpers/usebulmaclasses.md): All Bulma utility helpers can be used.

---

## Additional Resources

- [Bulma Dropdown Documentation](https://bulma.io/documentation/components/dropdown/)
- [Storybook: Dropdown Stories](https://bestax.io/storybook/?path=/story/components-dropdown--default)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Dropdown />`, `<Dropdown.Item />`, and `<Dropdown.Divider />` for utility-based styling.
:::

---

## Loading


## Overview

The `Loading` component provides a loading overlay with a spinner animation. It can be used as a full-page overlay or a container overlay to indicate loading states. Supports different sizes, color variants, optional cancel functionality, and custom loading messages.

---

## Import

```tsx

```

---

## Props

| Prop               | Type                                                                            | Default | Description                                           |
| ------------------ | ------------------------------------------------------------------------------- | ------- | ----------------------------------------------------- |
| `active`           | `boolean`                                                                       | `false` | Whether the loading overlay is visible.               |
| `isFullPage`       | `boolean`                                                                       | `false` | Cover the entire viewport.                            |
| `size`             | `'small'` \| `'medium'` \| `'large'`                                            | —       | Size of the loading spinner.                          |
| `color`            | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` | —       | Color variant for the spinner. Default is light grey. |
| `canCancel`        | `boolean`                                                                       | `false` | Show a cancel button and allow closing.               |
| `onCancel`         | `() => void`                                                                    | —       | Callback when cancel is triggered.                    |
| `children`         | `React.ReactNode`                                                               | —       | Content to display below the spinner.                 |
| `className`        | `string`                                                                        | —       | Additional CSS classes.                               |
| `overlayClassName` | `string`                                                                        | —       | Additional classes for the overlay.                   |
| `iconClassName`    | `string`                                                                        | —       | Additional classes for the spinner icon.              |
| `indicator`        | `React.ReactNode`                                                               | —       | Custom loading indicator element.                     |
| `overlay`          | `'light'` \| `'dark'` \| `'opaque'`                                             | —       | Style of the loading overlay.                         |
| ...                | All standard HTML and Bulma helper props                                        |         | (See [Helper Props](../helpers/usebulmaclasses))      |

---

## Usage

### Basic Loading

A simple loading overlay within a container.

```tsx live
function example() {
  return (
    <Box relative style={{ minHeight: '300px' }}>
      <Loading active>Loading...</Loading>
      <Paragraph>This content is behind the loading overlay.</Paragraph>
    </Box>
  );
}
```

:::caution
The container must have `position: relative` for the loading overlay to position correctly within it.
:::

---

### Without Message

Loading overlay without a text message.

```tsx live
function example() {
  return (
    <Box relative style={{ height: '200px' }}>
      <Loading active />
    </Box>
  );
}
```

---

### Spinner Sizes

Loading with different spinner sizes.

```tsx live
function example() {
  return (
    <Columns>
      <Column>
        <Box relative style={{ height: '200px' }}>
          <Loading active size="small">
            Small
          </Loading>
        </Box>
      </Column>
      <Column>
        <Box relative style={{ height: '200px' }}>
          <Loading active>Default</Loading>
        </Box>
      </Column>
      <Column>
        <Box relative style={{ height: '200px' }}>
          <Loading active size="medium">
            Medium
          </Loading>
        </Box>
      </Column>
      <Column>
        <Box relative style={{ height: '200px' }}>
          <Loading active size="large">
            Large
          </Loading>
        </Box>
      </Column>
    </Columns>
  );
}
```

---

### Spinner Colors

The spinner supports Bulma color variants. When no color is specified, the spinner defaults to a light grey matching the Buefy style.

```tsx live
function example() {
  return (
    <Columns isMultiline>
      <Column size="4">
        <Box relative style={{ height: '150px' }}>
          <Loading active>Default</Loading>
        </Box>
      </Column>
      <Column size="4">
        <Box relative style={{ height: '150px' }}>
          <Loading active color="primary">
            Primary
          </Loading>
        </Box>
      </Column>
      <Column size="4">
        <Box relative style={{ height: '150px' }}>
          <Loading active color="info">
            Info
          </Loading>
        </Box>
      </Column>
      <Column size="4">
        <Box relative style={{ height: '150px' }}>
          <Loading active color="success">
            Success
          </Loading>
        </Box>
      </Column>
      <Column size="4">
        <Box relative style={{ height: '150px' }}>
          <Loading active color="warning">
            Warning
          </Loading>
        </Box>
      </Column>
      <Column size="4">
        <Box relative style={{ height: '150px' }}>
          <Loading active color="danger">
            Danger
          </Loading>
        </Box>
      </Column>
    </Columns>
  );
}
```

---

### With Cancel Button

Loading overlay that can be cancelled.

```tsx live
function example() {
  const [isLoading, setIsLoading] = useState(true);

  return (
    <>
      <Box relative style={{ height: '200px' }}>
        <Loading
          active={isLoading}
          canCancel
          onCancel={() => setIsLoading(false)}
        >
          Click cancel or press Escape
        </Loading>
        <Paragraph p="4">Content behind the overlay.</Paragraph>
      </Box>
      {!isLoading && (
        <Button color="primary" mt="4" onClick={() => setIsLoading(true)}>
          Show Loading
        </Button>
      )}
    </>
  );
}
```

---

### Full Page Loading

A full-page loading overlay that covers the entire viewport.

```tsx live
function example() {
  const [isLoading, setIsLoading] = useState(false);

  return (
    <>
      <Button color="primary" onClick={() => setIsLoading(true)}>
        Show Full Page Loading
      </Button>
      <Loading
        active={isLoading}
        isFullPage
        canCancel
        onCancel={() => setIsLoading(false)}
      >
        Full page loading... Click cancel or press Escape
      </Loading>
    </>
  );
}
```

:::tip
When `isFullPage` is true and the loading is active, body scroll is automatically disabled.
:::

---

### Triggered by Button

Common pattern where loading is triggered by a button action.

```tsx live
function example() {
  const [isLoading, setIsLoading] = useState(false);

  const handleClick = () => {
    setIsLoading(true);
    // Simulate async operation
    setTimeout(() => setIsLoading(false), 2000);
  };

  return (
    <Box relative p="5" style={{ height: '150px' }}>
      <Loading active={isLoading}>Loading data...</Loading>
      <Paragraph>Click the button to see the loading overlay.</Paragraph>
      <Button color="primary" onClick={handleClick} disabled={isLoading} mt="3">
        Load Data
      </Button>
    </Box>
  );
}
```

---

## Cancel Methods

When `canCancel` is true, the loading can be cancelled by:

1. **Clicking the Cancel button** - A button appears below the spinner
2. **Pressing the Escape key** - Keyboard shortcut for accessibility
3. **Clicking the overlay** - Clicking the semi-transparent background

---

## Accessibility

- Uses `role="alert"` to announce loading state to screen readers
- Has `aria-busy="true"` to indicate loading status
- Has `aria-label="Loading"` for the loading container
- Cancel button has proper `aria-label` for accessibility
- Escape key support for cancelling (when `canCancel` is true)

---

## Related

- [Skeleton](../elements/skeleton.md) - Placeholder loading states
- [Progress](../elements/progress.md) - Progress bar component

---

## Menu


## Overview

The `Menu` component provides Bulma's vertical navigation menu: a simple, accessible sidebar or section menu for your Bulma React UI. It supports labels, nested menu lists, active states, custom links, and all Bulma/utility helper props. Use it for dashboards, sidebars, admin panels, or any grouped navigation.

:::info
Menu supports unlimited nesting and lets you use any link or router component via the `as` prop on `Menu.Item`.
:::

---

## Import

```tsx

```

---

## Props

### Menu

| Prop        | Type                   | Default | Description                                      |
| ----------- | ---------------------- | ------- | ------------------------------------------------ |
| `className` | `string`               | —       | Additional CSS classes.                          |
| `children`  | `React.ReactNode`      | —       | Menu content (labels, lists, items, etc).        |
| ...         | All Bulma helper props |         | (See [Helper Props](../helpers/usebulmaclasses)) |

### Menu.Label

| Prop        | Type              | Default | Description         |
| ----------- | ----------------- | ------- | ------------------- |
| `className` | `string`          | —       | Additional classes. |
| `children`  | `React.ReactNode` | —       | Label content.      |

### Menu.List

| Prop        | Type              | Default | Description                                 |
| ----------- | ----------------- | ------- | ------------------------------------------- |
| `className` | `string`          | —       | Additional classes.                         |
| `children`  | `React.ReactNode` | —       | List items (`Menu.Item`). Supports nesting. |

### Menu.Item

| Prop        | Type                        | Default | Description                                      |
| ----------- | --------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                    | —       | Additional classes.                              |
| `children`  | `React.ReactNode`           | —       | Label, and optionally nested `Menu.List`.        |
| `active`    | `boolean`                   | —       | Highlight item as active.                        |
| `href`      | `string`                    | —       | Href for link items (if rendered as ``).      |
| `as`        | `React.ElementType`         | `'a'`   | Custom link component (e.g. `Link` from router). |
| ...         | All `` and helper props |         | Standard HTML/li/utility props.                  |

---

## Usage

### Basic Menu with Nested Lists

To create a sidebar or section menu with multiple levels, use the `Menu` component with nested `Menu.Label` and `Menu.List` subcomponents. You can nest `Menu.List` inside a `Menu.Item` to create hierarchical navigation. Use the `active` prop on a `Menu.Item` to highlight the current selection. This pattern is ideal for dashboards, admin panels, or any grouped navigation area, and you can apply Bulma helper props for layout and color customization.

```tsx live
<Menu style={{ maxWidth: 300 }}>
  <Menu.Label>General</Menu.Label>
  <Menu.List>
    <Menu.Item>Dashboard</Menu.Item>
    <Menu.Item>Customers</Menu.Item>
  </Menu.List>
  <Menu.Label>Administration</Menu.Label>
  <Menu.List>
    <Menu.Item>Team Settings</Menu.Item>
    <Menu.Item active>
      Manage Your Team
      <Menu.List>
        <Menu.Item>Members</Menu.Item>
        <Menu.Item>Plugins</Menu.Item>
        <Menu.Item>Add a member</Menu.Item>
      </Menu.List>
    </Menu.Item>
    <Menu.Item>Invitations</Menu.Item>
    <Menu.Item>Cloud Storage Environment Settings</Menu.Item>
    <Menu.Item>Authentication</Menu.Item>
  </Menu.List>
  <Menu.Label>Transactions</Menu.Label>
  <Menu.List>
    <Menu.Item>Payments</Menu.Item>
    <Menu.Item>Transfers</Menu.Item>
    <Menu.Item>Balance</Menu.Item>
  </Menu.List>
</Menu>
```

---

### Custom Link Component

Use the `as` prop on `Menu.Item` to render a custom link component, such as a router link. This enables seamless integration with client-side routing libraries, allowing you to pass additional props like `to` or `href` as needed for navigation.

```tsx live
// import { Link } from 'react-router-dom';
function example() {
  const Link = props => {props.children};
  return (
    <Menu>
      <Menu.Label>App</Menu.Label>
      <Menu.List>
        <Menu.Item as={Link} to="/dashboard">
          Dashboard
        </Menu.Item>
        <Menu.Item as={Link} to="/settings">
          Settings
        </Menu.Item>
      </Menu.List>
    </Menu>
  );
}
```

---

### Active Menu Item

Highlight a menu entry by setting the `active` prop on a `Menu.Item`. This visually indicates the user's current location within the navigation structure, making it easier to orient within the app or section.

```tsx live
<Menu>
  <Menu.Label>Active Example</Menu.Label>
  <Menu.List>
    <Menu.Item>Overview</Menu.Item>
    <Menu.Item active>Current Page</Menu.Item>
    <Menu.Item>Other</Menu.Item>
  </Menu.List>
</Menu>
```

---

### Deeply Nested Menu

Create multi-level navigation by nesting `Menu.List` components inside `Menu.Item`. This is ideal for complex sidebars or admin panels with grouped and deeply nested navigation links.

```tsx live
<Menu>
  <Menu.Label>Levels</Menu.Label>
  <Menu.List>
    <Menu.Item>
      Level 1
      <Menu.List>
        <Menu.Item>
          Level 2
          <Menu.List>
            <Menu.Item>Level 3</Menu.Item>
          </Menu.List>
        </Menu.Item>
      </Menu.List>
    </Menu.Item>
  </Menu.List>
</Menu>
```

---

## Accessibility

- The root `Menu` renders as `<aside class="menu">`.
- Use semantic nesting (`Menu.List` inside `Menu.Item`) for submenus.
- Ensure each item is focusable and accessible if interactive.

:::note
For router integrations, pass the correct `as` and `to`/`href` props to `Menu.Item`.
:::

---

## Related Components

- [`Sidebar`](./sidebar.md): For slide-out navigation panels using Menu.
- [`Panel`](./panel.md): For alternate sidebar/navigation layouts.
- [Helper Props](../helpers/usebulmaclasses.md): All Bulma utility helpers are supported.

---

## Additional Resources

- [Bulma Menu Documentation](https://bulma.io/documentation/components/menu/)
- [Storybook: Menu Stories](https://bestax.io/storybook/?path=/story/components-menu--basic)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Menu />` and its subcomponents for powerful utility-based styling.
:::

---

## Message


## Overview

The `Message` component provides Bulma's flexible notice/message box for your Bulma React UI. It supports color, optional headers, close buttons, custom content, and Bulma helper classes for text/background. Use it for inline feedback, status messages, alerts, or general notifications.

:::info
Supports Bulma color modifiers, sizes, and both header/body sections. The close button is optional and triggers your `onClose` callback.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `color`     | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`                                                                                                                                                                                                          | —       | Bulma color modifier for the message.            |
| `title`     | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Title string/node (renders header section).      |
| `onClose`   | `() => void`                                                                                                                                                                                                                                                                             | —       | Callback for the close ("X") button.             |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color for the message (Bulma helper).       |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color for the message (Bulma helper). |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Body content for the message.                    |
| ...         | All standard HTML and Bulma helper props (see [Helper Props](../helpers/usebulmaclasses))                                                                                                                                                                                                |         | Utility and accessibility props.                 |

---

## Usage

### Message with Header (per color)

To display a message box with a header, use the `Message` component with the `color` and `title` props. This allows you to visually distinguish messages by context—such as `primary`, `info`, `success`, `warning`, or `danger`—and provide a clear heading for the content. The `onClose` prop adds a close button for dismissible messages, and you can use Bulma helper props for further customization.

```tsx live
<>
  <Message color="primary" title="Primary">
    This is a primary message.
  </Message>
  <Message color="link" title="Link">
    This is a link message.
  </Message>
  <Message color="info" title="Info">
    This is an info message.
  </Message>
  <Message color="success" title="Success">
    This is a success message.
  </Message>
  <Message color="warning" title="Warning">
    This is a warning message.
  </Message>
  <Message color="danger" title="Danger">
    This is a danger message.
  </Message>
</>
```

---

### Message Body Only (no header)

You can omit the `title` prop to render a message with only a body section. This is useful for simple notifications or inline feedback without a heading.

```tsx live
<>
  <Message color="primary">This is a primary message with no header.</Message>
  <Message color="danger">This is a danger message with no header.</Message>
</>
```

---

### Dismissible Message

Add the `onClose` prop to make the message dismissible. When the close button is clicked, your callback will be triggered, allowing you to hide or remove the message from the UI.

```tsx live
function example() {
  const [open, setOpen] = useState(true);

  return (
    <>
      {open && (
        <Message color="info" title="Dismiss Me" onClose={() => setOpen(false)}>
          You can close this message by clicking the X button.
        </Message>
      )}
    </>
  );
}
```

---

### Sizes

You can use Bulma size helpers or custom styles to adjust the size of the message box for different contexts.

```tsx live
<>
  <Message title="Default Size">This is the default size message.</Message>
  <Message title="Small">This is a small message.</Message>
  <Message title="Medium">This is a medium message.</Message>
  <Message title="Large">This is a large message.</Message>
</>
```

---

## Compound Components

The `Message` component also supports a compound component API for maximum flexibility. This allows you to compose messages with fine-grained control over each section.

### Message.Header

Renders the message header section with proper styling.

**Props:**

- `className?`: Additional CSS classes
- All standard HTML attributes for ``

### Message.Body

Renders the message body section.

**Props:**

- `className?`: Additional CSS classes
- All standard HTML attributes for ``

### Compound Component Examples

#### Complete Message with Compound Components

```tsx live
<Message color="info">
  <Message.Header>
    <Paragraph>Compound Component Message</Paragraph>
    <Delete aria-label="delete" />
  </Message.Header>
  <Message.Body>
    <Paragraph>
      This message is built using compound components for maximum flexibility
      and control over each section.
    </Paragraph>
    <Paragraph>
      You can include multiple paragraphs and elements in the body.
    </Paragraph>
  </Message.Body>
</Message>
```

#### Minimal Message with Body Only

```tsx live
<Message color="success">
  <Message.Body>
    <Paragraph>
      A simple message using only the Message.Body compound component.
    </Paragraph>
  </Message.Body>
</Message>
```

#### Header-Only Message

```tsx live
<Message color="warning">
  <Message.Header>
    <Paragraph>Header-only message</Paragraph>
    <Delete aria-label="delete" />
  </Message.Header>
</Message>
```

#### Mixed Approach

You can combine the traditional prop-based API with compound components:

```tsx live
<Message color="danger" title="Mixed Approach">
  <Message.Body bgColor="light">
    <Paragraph>
      You can mix prop-based and compound component approaches!
    </Paragraph>
    <Paragraph>
      This message uses the title prop but compound components for the body.
    </Paragraph>
  </Message.Body>
</Message>
```

---

## Accessibility

- The message is rendered as `<article class="message">`.
- If `onClose` is provided, a close button with `aria-label="delete"` is rendered.
- For optimal accessibility, use clear and descriptive titles/content.

:::note
Always provide a visible or accessible way to dismiss important, interruptive messages.
:::

---

## Related Components

- [`Notification`](../elements/notification.md): For simpler, single-box notifications.
- [Helper Props](../helpers/usebulmaclasses.md): All Bulma utility helpers can be used.

---

## Additional Resources

- [Bulma Message Documentation](https://bulma.io/documentation/components/message/)
- [Storybook: Message Stories](https://bestax.io/storybook/?path=/story/components-message--primary)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Message />` for powerful utility-based styling.
:::

---

## Modal


## Overview

The `Modal` component provides a flexible, accessible modal dialog for your Bulma React UI. It supports both Bulma's modal-card and modal-content variants, with options for title, footer, custom content, color helpers, and close callbacks. Easily control visibility via the `active` or `isActive` prop and handle closing with `onClose`.

The Modal component supports two APIs:

- **Legacy Props API**: Use `modalCardTitle` and `modalCardFoot` props for simple modals
- **Compound Components API**: Use `Modal.Background`, `Modal.Card`, `Modal.Content`, and `Modal.Close` for full control and better readability

:::info
Use `Modal` for dialogs, confirmations, forms, or custom popover content. Supports card-style layouts (header/body/footer) or arbitrary content modals.
:::

---

## Import

```tsx

```

---

## Props

### Main Modal Props

| Prop             | Type                                                                                                                                                                                                                                                                                     | Default | Description                                                                            |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------------- |
| `active`         | `boolean`                                                                                                                                                                                                                                                                                | `false` | Whether the modal is open/visible.                                                     |
| `isActive`       | `boolean`                                                                                                                                                                                                                                                                                | `false` | Alias for `active`. Whether the modal is open/visible.                                 |
| `onClose`        | `() => void`                                                                                                                                                                                                                                                                             | —       | Callback invoked to request modal close (background or close button).                  |
| `type`           | `'card'` \| `'content'`                                                                                                                                                                                                                                                                  | auto    | Modal style: `'card'` for modal-card, `'content'` for modal-content. (Legacy API only) |
| `modalCardTitle` | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Title/header for modal-card variant. (Legacy API only)                                 |
| `modalCardFoot`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Footer for modal-card variant. (Legacy API only)                                       |
| `textColor`      | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color for modal content.                                                          |
| `bgColor`        | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color for modal content.                                                    |
| `className`      | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes for the modal.                                                  |
| `children`       | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Modal body/content.                                                                    |
| ...              | All standard HTML and Bulma helper props                                                                                                                                                                                                                                                 |         | (See [Helper Props](../helpers/usebulmaclasses))                                       |

### Compound Components

| Component          | Description                                                                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Modal.Background` | Modal background overlay (supports onClick)                                                                                                                  |
| `Modal.Content`    | Modal content wrapper                                                                                                                                        |
| `Modal.Card`       | Modal card wrapper                                                                                                                                           |
| `Modal.Card.Head`  | Modal card header                                                                                                                                            |
| `Modal.Card.Title` | Modal card title                                                                                                                                             |
| `Modal.Card.Body`  | Modal card body                                                                                                                                              |
| `Modal.Card.Foot`  | Modal card footer                                                                                                                                            |
| `Modal.Close`      | Modal close button. Props: `variant` ('delete' [default] for card headers, 'floating' for overlay), `size` ('small', 'medium', 'large') for floating variant |

---

## Usage

### Modal Card (with title and footer)

To display a modal dialog with a header and footer, use the `Modal` component with the `active` prop to control visibility, and provide `modalCardTitle` and `modalCardFoot` for the card layout. The `onClose` prop handles closing the modal, and you can use Bulma color helpers for further customization. This pattern is ideal for forms, confirmations, or any content that requires user attention in a focused overlay.

```tsx live
function example() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button color="success" onClick={() => setOpen(true)}>
        Show Modal
      </Button>
      <Modal
        active={open}
        onClose={() => setOpen(false)}
        modalCardTitle="Modal Card Title"
        modalCardFoot={
          <Buttons>
            <Button color="success">Save</Button>
            <Button>Cancel</Button>
          </Buttons>
        }
      >
        Modal card body content goes here...
      </Modal>
    </>
  );
}
```

---

### Modal Card (title only)

Provide only the `modalCardTitle` prop to display a modal card with a header and body, but no footer. This is useful for simple dialogs or information popups that do not require actions in the footer area.

```tsx live
function example() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button color="success" onClick={() => setOpen(true)}>
        Show Modal
      </Button>
      <Modal
        active={open}
        onClose={() => setOpen(false)}
        modalCardTitle="Modal Card Title Only"
      >
        Modal body content...
      </Modal>
    </>
  );
}
```

---

### Modal Card (footer only)

Provide only the `modalCardFoot` prop to display a modal card with a footer and body, but no header. This is useful for confirmation dialogs or actions that do not require a title.

```tsx live
function example() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button color="success" onClick={() => setOpen(true)}>
        Show Modal
      </Button>
      <Modal
        active={open}
        onClose={() => setOpen(false)}
        modalCardFoot={<Button color="success">Save</Button>}
      >
        Modal body content...
      </Modal>
    </>
  );
}
```

---

### Modal Content (no card title or footer)

Omit both `modalCardTitle` and `modalCardFoot` to render a modal with only custom content. This is ideal for popovers, custom layouts, or when you want full control over the modal's appearance.

```tsx live
function example() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button color="success" onClick={() => setOpen(true)}>
        Show Modal
      </Button>
      <Modal active={open} onClose={() => setOpen(false)}>
        <Box>
          <Title size="4">Custom Content</Title>
          <Paragraph>Put any content here!</Paragraph>
        </Box>
      </Modal>
    </>
  );
}
```

---

### Explicit Modal Types

#### Force content style

Set the `type` prop to `content` to force the modal to use the content style, regardless of whether a title or footer is provided. This is useful for custom layouts or when you want to avoid the card structure.

```tsx live
function example() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button color="success" onClick={() => setOpen(true)}>
        Show Modal
      </Button>
      <Modal active={open} onClose={() => setOpen(false)} type="content">
        Custom content modal (forced type="content")
      </Modal>
    </>
  );
}
```

#### Force card style

Set the `type` prop to `card` to force the modal to use the card style, even if no title or footer is provided. This is helpful for consistent styling across your app.

```tsx live
function example() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button color="success" onClick={() => setOpen(true)}>
        Show Modal
      </Button>
      <Modal active={open} onClose={() => setOpen(false)} type="card">
        Modal card body (forced type="card")
      </Modal>
    </>
  );
}
```

---

### Compound Components API

#### Modal.Card with compound components

The compound components API provides more flexibility and better readability for complex modals. Use `Modal.Background`, `Modal.Card`, and related sub-components for full control over the modal structure.

```tsx live
function example() {
  const [open, setOpen] = useState(false);
  const closeModal = () => setOpen(false);

  return (
    <>
      <Button color="success" onClick={() => setOpen(true)}>
        Show Modal
      </Button>
      <Modal isActive={open}>
        <Modal.Background onClick={closeModal} />
        <Modal.Card>
          <Modal.Card.Head>
            <Modal.Card.Title>Compound Component Modal</Modal.Card.Title>
            <Modal.Close onClick={closeModal} />
          </Modal.Card.Head>
          <Modal.Card.Body>
            This modal uses the compound components API for better control and
            readability.
          </Modal.Card.Body>
          <Modal.Card.Foot>
            <Buttons>
              <Button color="success" onClick={closeModal}>
                Save
              </Button>
              <Button onClick={closeModal}>Cancel</Button>
            </Buttons>
          </Modal.Card.Foot>
        </Modal.Card>
      </Modal>
    </>
  );
}
```

#### Modal.Content with compound components

For custom content modals, use `Modal.Content` with `Modal.Close` (use `variant="floating"` for the overlay close button):

```tsx live
function example() {
  const [open, setOpen] = useState(false);
  const closeModal = () => setOpen(false);

  return (
    <>
      <Button color="success" onClick={() => setOpen(true)}>
        Show Modal
      </Button>
      <Modal isActive={open}>
        <Modal.Background onClick={closeModal} />
        <Modal.Content>
          <Box>
            <Title size="4">Custom Content</Title>
            <Paragraph>Using compound components for full control!</Paragraph>
          </Box>
        </Modal.Content>
        <Modal.Close variant="floating" onClick={closeModal} />
      </Modal>
    </>
  );
}
```

---

## Accessibility

- The modal root uses Bulma’s structure and ARIA roles for accessibility.
- The modal background closes the modal on click (`onClose` required).
- Close buttons are provided for both modal-card and modal-content variants.
- Keyboard/screen reader accessibility is supported, but for focus trap or escape key handling, implement those patterns in your app as needed.

:::note
Always provide an `onClose` handler for accessibility and to allow users to dismiss the modal.
:::

---

## Related Components

- [`Button`](../elements/button.md): Use for actions in modal footers.
- [`Field`](../form/field.md), [`Input`](../form/input.md): For forms inside modals.
- [Helper Props](../helpers/usebulmaclasses.md): All Bulma utility helpers can be used.

---

## Additional Resources

- [Bulma Modal Documentation](https://bulma.io/documentation/components/modal/)
- [Storybook: Modal Stories](https://bestax.io/storybook/?path=/story/components-modal--modal-card)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Modal />` for powerful utility-based styling.
:::

---

## Navbar


## Overview

The `Navbar` component implements Bulma's powerful, responsive navigation bar for your Bulma React UI. It supports color, transparency, fixed positioning, dropdowns, and granular composition with subcomponents for brand, menu, items, burger (mobile toggle), start/end, and rich dropdowns. Use it for main navigation, site branding, and complex menu layouts.

:::info
Compose your navigation using `Navbar`, `Navbar.Brand`, `Navbar.Burger`, `Navbar.Menu`, `Navbar.Start`, `Navbar.End`, `Navbar.Item`, `Navbar.Dropdown`, and more for full Bulma flexibility.
:::

---

## Import

```tsx

```

---

## Props

| Prop          | Type                                                                                                                                                                                                                                                                                     | Default | Description                                            |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------ |
| `color`       | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'dark'` \| `'light'` \| `'white'`                                                                                                                                                       | —       | Bulma color modifier for the navbar.                   |
| `bgColor`     | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color for the navbar.                       |
| `textColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color for the navbar.                             |
| `transparent` | `boolean`                                                                                                                                                                                                                                                                                | false   | Renders the navbar with a transparent background.      |
| `fixed`       | `'top'` \| `'bottom'`                                                                                                                                                                                                                                                                    | —       | Fixes the navbar to the top or bottom of the viewport. |
| `className`   | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                                |
| `children`    | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Navbar content (compose with subcomponents).           |
| ...           | All standard HTML and Bulma helper props                                                                                                                                                                                                                                                 |         | (See [Helper Props](../helpers/usebulmaclasses))       |

**Key Subcomponents:**

- `Navbar.Brand`: For logo and branding (left side)
- `Navbar.Burger`: Responsive menu toggle (mobile)
- `Navbar.Menu`: Collapsible content (contains `Navbar.Start` and `Navbar.End`)
- `Navbar.Start`: Left-aligned menu area
- `Navbar.End`: Right-aligned menu area
- `Navbar.Item`: Navigation links, buttons, or custom content
- `Navbar.Link`: Dropdown trigger with arrow indicator (use as first child of `Navbar.Dropdown`)
- `Navbar.Dropdown`: Dropdown parent (with options for hover, up, right, active)
- `Navbar.DropdownMenu`: Dropdown menu container
- `Navbar.Divider`: Divider in dropdown menus

---

## Usage

### Complete Navbar with Burger and Menu

This example demonstrates a fully responsive navigation bar using `Navbar` and its subcomponents. The `Navbar.Burger` toggles the mobile menu, while `Navbar.Brand` displays branding or a logo. Use the `active` prop on `Navbar.Burger` and `Navbar.Menu` to control the open state. Compose navigation links and dropdowns within `Navbar.Start` and `Navbar.End` for flexible layouts. Customize with `color`, `bgColor`, `fixed`, and `transparent` props as needed.

```tsx live
function example() {
  const [active, setActive] = useState(false);

  return (
    <Navbar>
      <Navbar.Brand>
        <Navbar.Item href="#">
          
        </Navbar.Item>
        <Navbar.Burger
          active={active}
          onClick={() => setActive(a => !a)}
          aria-label="menu"
          aria-expanded={active}
        />
      </Navbar.Brand>
      <Navbar.Menu active={active}>
        <Navbar.Start>
          <Navbar.Item href="#">Home</Navbar.Item>
          <Navbar.Item href="#">Docs</Navbar.Item>
          <Navbar.Item href="#">About</Navbar.Item>
          <Navbar.Item href="#">Contact</Navbar.Item>
        </Navbar.Start>
        <Navbar.End>
          <Navbar.Item href="#">Login</Navbar.Item>
        </Navbar.End>
      </Navbar.Menu>
    </Navbar>
  );
}
```

---

### Brand Only

This example shows a simple navbar with just the brand logo. The `Navbar.Brand` component is used to contain the logo image, which links to the homepage or main section of the site.

```tsx live
<Navbar>
  <Navbar.Brand>
    <Navbar.Item href="#">
      
    </Navbar.Item>
  </Navbar.Brand>
</Navbar>
```

---

### Burger Only

Demonstrates the `Navbar.Burger` component, which is the mobile menu toggle. It doesn't have an associated menu in this snippet, but in practice, it would control the visibility of the `Navbar.Menu`.

:::note
The burger is only shown on touch/mobile viewports by default. The example below forces `display: flex` so you can see it on desktop.
:::

```tsx live
<Navbar>
  <Navbar.Burger
    aria-label="menu"
    aria-expanded={false}
    style={{ display: 'flex' }}
  />
</Navbar>
```

---

### Burger Active

Shows the `Navbar.Burger` in its active state, indicating that the menu it controls is open. The `active` prop is used to toggle this state.

```tsx live
<Navbar>
  <Navbar.Burger
    active
    aria-label="menu"
    aria-expanded
    style={{ display: 'flex' }}
  />
</Navbar>
```

---

### Menu with Start and End

This example illustrates a `Navbar.Menu` with `Navbar.Start` and `Navbar.End` sections. The start section could contain primary navigation links, while the end section might hold user account links like login or profile.

```tsx live
<Navbar>
  <Navbar.Menu active>
    <Navbar.Start>
      <Navbar.Item href="#">Home</Navbar.Item>
    </Navbar.Start>
    <Navbar.End>
      <Navbar.Item href="#">Login</Navbar.Item>
    </Navbar.End>
  </Navbar.Menu>
</Navbar>
```

---

### Navigation Links and Dropdowns

A more complex example with navigation links and a dropdown menu. The dropdown is used for additional links or actions related to the main navigation items.

```tsx live
<Navbar>
  <Navbar.Brand>
    <Navbar.Item>
      
    </Navbar.Item>
  </Navbar.Brand>
  <Navbar.Menu active>
    <Navbar.Start>
      <Navbar.Item href="#">Home</Navbar.Item>
      <Navbar.Item href="#">Docs</Navbar.Item>
      <Navbar.Dropdown hoverable>
        <Navbar.Link>More</Navbar.Link>
        <Navbar.DropdownMenu>
          <Navbar.Item href="#">About</Navbar.Item>
          <Navbar.Item href="#">Jobs</Navbar.Item>
          <Navbar.Item href="#">Contact</Navbar.Item>
          <Navbar.Divider />
          <Navbar.Item href="#">Report an issue</Navbar.Item>
        </Navbar.DropdownMenu>
      </Navbar.Dropdown>
    </Navbar.Start>
  </Navbar.Menu>
</Navbar>
```

---

### Transparent Navbar

Example of a navbar with a transparent background. This is often used for navbars that overlay content, like images or videos, giving a more integrated look.

```tsx live
<Navbar transparent>{/* ...brand and menu... */}</Navbar>
```

---

### Fixed Navbar

Shows the navbar fixed to the top of the viewport. This is useful for keeping the navigation accessible at all times as the user scrolls.

```tsx live
<Navbar fixed="top">{/* ...brand and menu... */}</Navbar>
```

---

### Dropdown Right

Demonstrates a dropdown menu aligned to the right. This can be useful for user account menus, notifications, or other contextual actions.

```tsx live
<Navbar>
  <Navbar.Menu active>
    <Navbar.End>
      <Navbar.Dropdown hoverable right>
        <Navbar.Link>Right Dropdown</Navbar.Link>
        <Navbar.DropdownMenu right>
          <Navbar.Item href="#">Profile</Navbar.Item>
          <Navbar.Item href="#">Settings</Navbar.Item>
        </Navbar.DropdownMenu>
      </Navbar.Dropdown>
    </Navbar.End>
  </Navbar.Menu>
</Navbar>
```

---

### Dropup

This example shows a dropdown menu that opens upwards, which can be useful in certain layout situations to prevent covering content. A `Hero` is placed above the navbar to give the dropup room to expand.

```tsx live
<>
  <Hero color="primary" size="small">
    <Hero.Body>
      <Title>Hero above Navbar</Title>
      <SubTitle>Hover "Dropup" below to see the menu open upward</SubTitle>
    </Hero.Body>
  </Hero>
  <Navbar>
    <Navbar.Menu active>
      <Navbar.Start>
        <Navbar.Dropdown hoverable up>
          <Navbar.Link>Dropup</Navbar.Link>
          <Navbar.DropdownMenu up>
            <Navbar.Item href="#">Up1</Navbar.Item>
            <Navbar.Item href="#">Up2</Navbar.Item>
          </Navbar.DropdownMenu>
        </Navbar.Dropdown>
      </Navbar.Start>
    </Navbar.Menu>
  </Navbar>
</>
```

---

### Dropdown without Arrow

Demonstrates a dropdown menu styled without the default arrow indicator. Set `arrowless` on `Navbar.Link` to remove the arrow indicator.

```tsx live
<Navbar>
  <Navbar.Menu active>
    <Navbar.Start>
      <Navbar.Dropdown hoverable>
        <Navbar.Link arrowless>No Arrow</Navbar.Link>
        <Navbar.DropdownMenu>
          <Navbar.Item href="#">A</Navbar.Item>
          <Navbar.Item href="#">B</Navbar.Item>
        </Navbar.DropdownMenu>
      </Navbar.Dropdown>
    </Navbar.Start>
  </Navbar.Menu>
</Navbar>
```

---

### Active Dropdown Item

Shows a dropdown menu with an active item. The active state is typically used to indicate the currently selected or active page/section.

```tsx live
<Navbar>
  <Navbar.Menu active>
    <Navbar.Start>
      <Navbar.Dropdown active>
        <Navbar.Link>Active Dropdown</Navbar.Link>
        <Navbar.DropdownMenu>
          <Navbar.Item href="#">A1</Navbar.Item>
          <Navbar.Item href="#">A2</Navbar.Item>
        </Navbar.DropdownMenu>
      </Navbar.Dropdown>
    </Navbar.Start>
  </Navbar.Menu>
</Navbar>
```

---

### Dropdown with Divider

This example shows a dropdown menu that includes a divider, which is used to separate groups of items within the menu for better organization and readability.

```tsx live
<Navbar>
  <Navbar.Menu active>
    <Navbar.Start>
      <Navbar.Dropdown hoverable>
        <Navbar.Link>With Divider</Navbar.Link>
        <Navbar.DropdownMenu>
          <Navbar.Item href="#">One</Navbar.Item>
          <Navbar.Item href="#">Two</Navbar.Item>
          <Navbar.Divider />
          <Navbar.Item href="#">Three</Navbar.Item>
        </Navbar.DropdownMenu>
      </Navbar.Dropdown>
    </Navbar.Start>
  </Navbar.Menu>
</Navbar>
```

---

### Color Modifiers

Demonstrates the use of different color modifiers for the navbar. Each `Navbar` component has a different color prop to showcase the available options.

```tsx live
function example() {
  const colors = [
    'primary',
    'link',
    'info',
    'success',
    'warning',
    'danger',
    'black',
    'dark',
    'light',
    'white',
  ];
  return (
    <>
      {colors.map(color => (
        <Navbar key={color} color={color} mb="2">
          <Navbar.Brand>
            <Navbar.Item href="#">
              
            </Navbar.Item>
          </Navbar.Brand>
          <Navbar.Menu active>
            <Navbar.Start>
              <Navbar.Item href="#">Home</Navbar.Item>
              <Navbar.Item href="#">Docs</Navbar.Item>
              <Navbar.Item href="#">Components</Navbar.Item>
            </Navbar.Start>
          </Navbar.Menu>
        </Navbar>
      ))}
    </>
  );
}
```

---

## Accessibility

- The root `Navbar` renders as `<nav role="navigation" aria-label="main navigation">`.
- Use semantic links (``) and buttons, and provide clear `aria-label` and `aria-expanded` for the burger toggle.
- Dropdowns and menus follow Bulma's structure for keyboard and screen reader accessibility.

:::note
For full accessibility in dropdowns, ensure that focus, keyboard navigation, and ARIA attributes are managed where needed.
:::

---

## Related Components

- [`Button`](../elements/button.md): For actions in Navbar.
- [`Icon`](../elements/icon.md): For icons inside Navbar items.
- [Helper Props](../helpers/usebulmaclasses.md): All Bulma utility helpers can be used.

---

## Additional Resources

- [Bulma Navbar Documentation](https://bulma.io/documentation/components/navbar/)
- [Storybook: Navbar Stories](https://bestax.io/storybook/?path=/story/components-navbar--default)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Navbar />` and its subcomponents for powerful utility-based styling.
:::

---

## Pagination


## Overview

The `Pagination` component provides a flexible, composable Bulma pagination navigation for your Bulma React UI. It supports color, size, alignment, rounded corners, disabled states, and both controlled and uncontrolled usage. Use the provided subcomponents to build complex paginations: previous/next buttons, page links, ellipsis, and custom content.

:::info
Use `Pagination` for navigating lists of results, pages, or any content split across screens.
:::

---

## Import

```tsx

```

---

## Props

| Prop           | Type                                                                                                                                                                                                                                                                                     | Default | Description                                         |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------- |
| `size`         | `'small'` \| `'medium'` \| `'large'`                                                                                                                                                                                                                                                     | —       | Size modifier.                                      |
| `align`        | `'centered'` \| `'right'`                                                                                                                                                                                                                                                                | —       | Alignment for the pagination.                       |
| `rounded`      | `boolean`                                                                                                                                                                                                                                                                                | `false` | Renders pagination with rounded corners.            |
| `total`        | `number`                                                                                                                                                                                                                                                                                 | —       | Total number of pages (for custom implementations). |
| `current`      | `number`                                                                                                                                                                                                                                                                                 | —       | Current page (for controlled implementations).      |
| `onPageChange` | `(page: number) => void`                                                                                                                                                                                                                                                                 | —       | Callback when a page is selected.                   |
| `className`    | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                             |
| `color`        | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'dark'` \| `'light'` \| `'white'`                                                                                                                                                       | —       | Color modifier for the pagination.                  |
| `textColor`    | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                                  |
| `bgColor`      | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                            |
| `children`     | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Custom pagination content (usually subcomponents).  |
| ...            | All standard HTML and Bulma helper props (see [Helper Props](../helpers/usebulmaclasses))                                                                                                                                                                                                |         | Utility and accessibility props.                    |

**Subcomponents:**

- `Pagination.List`: Container for page links and ellipsis.
- `Pagination.Link`: Page number or navigation link.
- `Pagination.Ellipsis`: Ellipsis separator.
- `Pagination.Previous`: "Previous" navigation button.
- `Pagination.Next`: "Next" navigation button.

---

## Usage

### Basic Pagination

This example demonstrates a basic pagination navigation using `Pagination`, `Pagination.List`, and `Pagination.Link` subcomponents. The `active` prop highlights the current page, while previous/next arrows and an ellipsis provide navigation for larger sets. Adjust the structure to match your data set or navigation needs.

```tsx live
<Pagination>
  <Pagination.List>
    <Pagination.Link>&laquo;</Pagination.Link>
    <Pagination.Link active>1</Pagination.Link>
    <Pagination.Link>2</Pagination.Link>
    <Pagination.Link>3</Pagination.Link>
    <Pagination.Ellipsis />
    <Pagination.Link>10</Pagination.Link>
    <Pagination.Link>&raquo;</Pagination.Link>
  </Pagination.List>
</Pagination>
```

---

### Sizes

Showcases the use of the `size` prop to render paginations in different sizes. Set `size="small"`, `size="medium"`, or `size="large"` to match the pagination to your UI scale. Each instance below demonstrates a different size, with the `active` prop indicating the current page.

```tsx live
<>
  <Pagination size="small" mb="2">
    <Pagination.List>
      <Pagination.Link>1</Pagination.Link>
      <Pagination.Link active>2</Pagination.Link>
      <Pagination.Link>3</Pagination.Link>
    </Pagination.List>
  </Pagination>
  <Pagination size="medium" mb="2">
    <Pagination.List>
      <Pagination.Link>1</Pagination.Link>
      <Pagination.Link active>2</Pagination.Link>
      <Pagination.Link>3</Pagination.Link>
    </Pagination.List>
  </Pagination>
  <Pagination size="large">
    <Pagination.List>
      <Pagination.Link>1</Pagination.Link>
      <Pagination.Link active>2</Pagination.Link>
      <Pagination.Link>3</Pagination.Link>
    </Pagination.List>
  </Pagination>
</>
```

---

### Alignment

Demonstrates the `align` prop to control the pagination alignment. Use `align="centered"` to center the pagination, or `align="right"` to align it to the right. This affects the entire pagination component, including the list of links and any additional content.

```tsx live
<>
  <Pagination align="centered" mb="2">
    <Pagination.List>
      <Pagination.Link>1</Pagination.Link>
      <Pagination.Link active>2</Pagination.Link>
      <Pagination.Link>3</Pagination.Link>
    </Pagination.List>
  </Pagination>
  <Pagination align="right">
    <Pagination.List>
      <Pagination.Link>1</Pagination.Link>
      <Pagination.Link active>2</Pagination.Link>
      <Pagination.Link>3</Pagination.Link>
    </Pagination.List>
  </Pagination>
</>
```

---

### Rounded

This example demonstrates the `rounded` prop, which renders the pagination with rounded corners for a softer, modern look. Use `rounded` to visually distinguish pagination controls or match your app's design language.

```tsx live
<Pagination rounded>
  <Pagination.List>
    <Pagination.Link>1</Pagination.Link>
    <Pagination.Link active>2</Pagination.Link>
    <Pagination.Link>3</Pagination.Link>
  </Pagination.List>
</Pagination>
```

---

### With Disabled

This example shows how to use the `disabled` prop on `Pagination.Link` to indicate unavailable navigation options. Here, the first link is disabled, preventing user interaction. Use `disabled` for links that should not be clickable, such as when on the first or last page.

```tsx live
<Pagination>
  <Pagination.List>
    <Pagination.Link disabled>&laquo;</Pagination.Link>
    <Pagination.Link active>1</Pagination.Link>
    <Pagination.Link>2</Pagination.Link>
    <Pagination.Link>3</Pagination.Link>
    <Pagination.Ellipsis />
    <Pagination.Link>10</Pagination.Link>
    <Pagination.Link>&raquo;</Pagination.Link>
  </Pagination.List>
</Pagination>
```

---

### Controlled Pagination

This example demonstrates a controlled pagination pattern using the `page` state and the `onClick` handler on each `Pagination.Link`. The current page is tracked in state, and clicking a link updates the page. Use this approach for paginations where you need to manage the current page in your app logic.

```tsx live
function example() {
  const [page, setPage] = useState(1);
  return (
    <>
      <Pagination>
        <Pagination.Previous
          disabled={page === 1}
          onClick={() => setPage(page - 1)}
        >
          Previous
        </Pagination.Previous>
        <Pagination.Next
          disabled={page === 5}
          onClick={() => setPage(page + 1)}
        >
          Next
        </Pagination.Next>
        <Pagination.List>
          {[1, 2, 3, 4, 5].map(i => (
            <Pagination.Link
              key={i}
              active={i === page}
              onClick={() => setPage(i)}
            >
              {i}
            </Pagination.Link>
          ))}
        </Pagination.List>
      </Pagination>
      <Paragraph mt="2">Current page: {page}</Paragraph>
    </>
  );
}
```

---

### Previous/Next with Pagination List

This example combines the `Pagination.Previous` and `Pagination.Next` subcomponents with a `Pagination.List` for a more advanced navigation pattern. Use `Previous` and `Next` for clear navigation controls, and combine with `Pagination.Link` and `Pagination.Ellipsis` for complex paginations.

```tsx live
<Pagination align="centered">
  <Pagination.Previous>Previous</Pagination.Previous>
  <Pagination.Next>Next page</Pagination.Next>
  <Pagination.List>
    <Pagination.Link aria-label="Goto page 1">1</Pagination.Link>
    <Pagination.Ellipsis />
    <Pagination.Link aria-label="Goto page 45">45</Pagination.Link>
    <Pagination.Link active aria-label="Page 46">
      46
    </Pagination.Link>
    <Pagination.Link aria-label="Goto page 47">47</Pagination.Link>
    <Pagination.Ellipsis />
    <Pagination.Link aria-label="Goto page 86">86</Pagination.Link>
  </Pagination.List>
</Pagination>
```

---

## Accessibility

- The root `Pagination` renders as a semantic `<nav role="navigation" aria-label="pagination">`.
- Use `aria-label` on page links for better screen reader support.
- Disabled and active states are handled with ARIA attributes and classes.

:::note
Pagination links are rendered as `` elements for accessibility and keyboard navigation.
:::

---

## Related Components

- [Helper Props](../helpers/usebulmaclasses.md): All Bulma utility helpers can be used.
- [`Button`](../elements/button.md): For custom page controls if needed.

---

## Additional Resources

- [Bulma Pagination Documentation](https://bulma.io/documentation/components/pagination/)
- [Storybook: Pagination Stories](https://bestax.io/storybook/?path=/story/components-pagination--basic)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Pagination />` and its subcomponents for utility-based styling.
:::

---

## Panel


## Overview

The `Panel` component implements Bulma's versatile panel block for React. It provides a convenient way to display lists, filters, navigation menus, or grouped actions in a card-like vertical container. The Panel supports color modifiers, search, tabs, icons, selectable blocks, and comes with several subcomponents for every panel part.

:::info
Use `Panel` for sidebar menus, filter lists, admin navigation, or any grouped interface actions.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                               | Default | Description                                     |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------- |
| `color`     | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'dark'` \| `'light'` \| `'white'` | —       | Bulma color modifier for the panel.             |
| `className` | `string`                                                                                                                           | —       | Additional CSS classes.                         |
| `children`  | `React.ReactNode`                                                                                                                  | —       | Panel content (usually includes subcomponents). |
| ...         | All standard HTML and Bulma helper props (see [Helper Props](../helpers/usebulmaclasses))                                          |         | Utility and accessibility props.                |

**Subcomponents:**

- `Panel.Heading`: Main heading (renders as ``)
- `Panel.Tabs`: Panel tabs (renders as ``)
- `Panel.Block`: Individual panel block (renders as ``)
- `Panel.Icon`: Icon wrapper with panel styling (renders as ``). Accepts all Icon props (`name`, `variant`, `features`, etc.)
- `Panel.InputBlock`: Search input with icon (renders as ``)
- `Panel.CheckboxBlock`: Checkbox block (renders as `<label class="panel-block">`)
- `Panel.ButtonBlock`: Call-to-action button (renders as `<button />`)

---

## Usage

### Complete Panel (Revolutionary Figures)

This example shows a complete panel layout using `Panel` and its subcomponents. The `Panel.Heading` provides a title, `Panel.InputBlock` adds a search field, and `Panel.Tabs` enables filtering. Use `Panel.Block` for each selectable item, optionally with an `active` state, and `Panel.Icon` to display icons. This structure is ideal for sidebars, filter lists, or admin menus. The `color` prop customizes the panel's appearance.

```tsx live
<Panel>
  <Panel.Heading>Revolutionary Figures</Panel.Heading>
  <Panel.InputBlock placeholder="Search" />
  <Panel.Tabs>
    All
    Patriots
    Loyalists
    Battles
    Documents
  </Panel.Tabs>
  <Panel.Block active>
    <Panel.Icon name="user" variant="solid" />
    George Washington
  </Panel.Block>
  <Panel.Block>
    <Panel.Icon name="user" variant="solid" />
    Alexander Hamilton
  </Panel.Block>
  <Panel.Block>
    <Panel.Icon name="user" variant="solid" />
    Benedict Arnold
  </Panel.Block>
  <Panel.Block>
    <Panel.Icon name="user" variant="solid" />
    John Adams
  </Panel.Block>
  <Panel.Block>
    <Panel.Icon name="flag" variant="solid" />
    Battle of Saratoga
  </Panel.Block>
  <Panel.Block>
    <Panel.Icon name="flag" variant="solid" />
    Treaty of Paris
  </Panel.Block>
  <Panel.Block>
    <Panel.Icon name="flag" variant="solid" />
    Bunker Hill
  </Panel.Block>
  <Panel.CheckboxBlock>remember me</Panel.CheckboxBlock>
  <Panel.ButtonBlock>Reset all filters</Panel.ButtonBlock>
</Panel>
```

---

### Color Variants

This example demonstrates the `Panel` component's color variants. The `color` prop applies Bulma's color modifiers to the panel. Each panel in this example uses a different color, showcasing the flexibility of the `Panel` component in adapting to various design requirements.

```tsx live
<>
  {[
    'primary',
    'link',
    'info',
    'success',
    'warning',
    'danger',
    'black',
    'dark',
    'light',
    'white',
  ].map(color => (
    <Panel key={color} color={color}>
      <Panel.Heading>
        {color.charAt(0).toUpperCase() + color.slice(1)} Panel
      </Panel.Heading>
      <Panel.InputBlock placeholder="Search" />
      <Panel.Block active>
        <Panel.Icon name="user" variant="solid" />
        George Washington
      </Panel.Block>
      <Panel.Block>
        <Panel.Icon name="user" variant="solid" />
        Marquis de Lafayette
      </Panel.Block>
      <Panel.Block>
        <Panel.Icon name="user" variant="solid" />
        Nathanael Greene
      </Panel.Block>
      <Panel.Block>
        <Panel.Icon name="flag" variant="solid" />
        Battle of Trenton
      </Panel.Block>
      <Panel.Block>
        <Panel.Icon name="flag" variant="solid" />
        Yorktown
      </Panel.Block>
      <Panel.ButtonBlock>Reset all filters</Panel.ButtonBlock>
    </Panel>
  ))}
</>
```

---

## Accessibility

- The root panel renders as a semantic `<nav>` for navigation/landmark.
- Use headings, links, and buttons with appropriate labels for best accessibility.
- The `Panel.Block` by default renders as an anchor ``, but can be customized for interactive blocks.

:::note
For keyboard navigation, ensure interactive Panel blocks are focusable and provide clear visual states.
:::

---

## Related Components

- [`Icon`](../elements/icon.md): For icons inside `Panel.Icon`.
- [Helper Props](../helpers/usebulmaclasses.md): All Bulma utility helpers can be used.

---

## Additional Resources

- [Bulma Panel Documentation](https://bulma.io/documentation/components/panel/)
- [Storybook: Panel Stories](https://bestax.io/storybook/?path=/story/components-panel--revolutionary-war)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Panel />` and its subcomponents for powerful utility-based styling.
:::

---

## Sidebar


## Overview

The `Sidebar` component provides a slide-out navigation panel that appears from the left or right side of the screen. It's ideal for mobile navigation, settings panels, or any content that should overlay the main interface.

---

## Import

```tsx

```

---

## Props

| Prop           | Type                                     | Default   | Description                                      |
| -------------- | ---------------------------------------- | --------- | ------------------------------------------------ |
| `isOpen`       | `boolean`                                | —         | Whether the sidebar is open (required).          |
| `onClose`      | `() => void`                             | —         | Callback when sidebar should close.              |
| `position`     | `'left'` \| `'right'`                    | `'left'`  | Which side the sidebar appears from.             |
| `width`        | `string`                                 | `'260px'` | Custom width of the sidebar.                     |
| `fullWidth`    | `boolean`                                | `false`   | Sidebar takes full width (mobile-style).         |
| `overlay`      | `boolean`                                | `true`    | Show overlay behind sidebar.                     |
| `overlayClose` | `boolean`                                | `true`    | Close sidebar when overlay is clicked.           |
| `escapeClose`  | `boolean`                                | `true`    | Close sidebar on Escape key.                     |
| `canCancel`    | `boolean`                                | `true`    | Allow closing the sidebar.                       |
| `inline`       | `boolean`                                | `false`   | Renders inline instead of using a portal.        |
| `children`     | `React.ReactNode`                        | —         | Content to display in the sidebar.               |
| `className`    | `string`                                 | —         | Additional CSS classes.                          |
| `ref`          | `React.Ref<HTMLElement>`                 | —         | Ref forwarded to the sidebar element.            |
| ...            | All standard HTML and Bulma helper props |           | (See [Helper Props](../helpers/usebulmaclasses)) |

### Sidebar.Header

Container for the sidebar header. Accepts all standard `` HTML attributes.

### Sidebar.Title

Title text inside the header. Accepts all standard `` HTML attributes.

### Sidebar.Close

Close button for the sidebar. Accepts all standard `<button>` HTML attributes.

### Sidebar.Body

Main content area of the sidebar. Accepts all standard `` HTML attributes.

### Sidebar.Footer

Footer area of the sidebar. Accepts all standard `` HTML attributes.

---

## Usage

:::info
The examples below use the `inline` prop so the sidebar renders inside the live preview. In real apps, omit `inline` so the sidebar uses a portal (rendered at document.body) for proper stacking above all page content.
:::

### Basic Sidebar

A simple sidebar with navigation menu. Compose the sidebar with `Sidebar.Header`, `Sidebar.Title`, `Sidebar.Close`, and `Sidebar.Body` subcomponents.

```tsx live
function example() {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <>
      <Button color="primary" onClick={() => setIsOpen(true)}>
        Open Sidebar
      </Button>
      <Sidebar inline isOpen={isOpen} onClose={() => setIsOpen(false)}>
        <Sidebar.Header>
          <Sidebar.Title>Navigation</Sidebar.Title>
          <Sidebar.Close onClick={() => setIsOpen(false)} />
        </Sidebar.Header>
        <Sidebar.Body>
          <Menu>
            <Menu.Label>General</Menu.Label>
            <Menu.List>
              <Menu.Item href="#">Dashboard</Menu.Item>
              <Menu.Item active href="#">
                Settings
              </Menu.Item>
              <Menu.Item href="#">Profile</Menu.Item>
            </Menu.List>
            <Menu.Label>Administration</Menu.Label>
            <Menu.List>
              <Menu.Item href="#">Users</Menu.Item>
              <Menu.Item href="#">Permissions</Menu.Item>
            </Menu.List>
          </Menu>
        </Sidebar.Body>
      </Sidebar>
    </>
  );
}
```

---

### Right-side Sidebar

Sidebar that slides in from the right.

```tsx live
function example() {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <>
      <Button color="info" onClick={() => setIsOpen(true)}>
        Open Right Sidebar
      </Button>
      <Sidebar
        inline
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        position="right"
      >
        <Sidebar.Header>
          <Sidebar.Title>Settings</Sidebar.Title>
          <Sidebar.Close onClick={() => setIsOpen(false)} />
        </Sidebar.Header>
        <Sidebar.Body>
          <Paragraph>Configure your preferences here.</Paragraph>
        </Sidebar.Body>
      </Sidebar>
    </>
  );
}
```

---

### Custom Width

Sidebar with custom width.

```tsx live
function example() {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <>
      <Button color="success" onClick={() => setIsOpen(true)}>
        Open Wide Sidebar
      </Button>
      <Sidebar
        inline
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        width="400px"
      >
        <Sidebar.Header>
          <Sidebar.Title>Wide Panel</Sidebar.Title>
          <Sidebar.Close onClick={() => setIsOpen(false)} />
        </Sidebar.Header>
        <Sidebar.Body>
          <Paragraph>This sidebar has a custom width of 400px.</Paragraph>
        </Sidebar.Body>
      </Sidebar>
    </>
  );
}
```

---

### Full Width (Mobile Style)

Full-width sidebar for mobile navigation.

```tsx live
function example() {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <>
      <Button color="warning" onClick={() => setIsOpen(true)}>
        Open Full Width
      </Button>
      <Sidebar
        inline
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        fullWidth
      >
        <Sidebar.Header>
          <Sidebar.Title>Full Width Panel</Sidebar.Title>
          <Sidebar.Close onClick={() => setIsOpen(false)} />
        </Sidebar.Header>
        <Sidebar.Body>
          <Menu>
            <Menu.List>
              <Menu.Item href="#">Home</Menu.Item>
              <Menu.Item href="#">Products</Menu.Item>
              <Menu.Item href="#">About</Menu.Item>
              <Menu.Item href="#">Contact</Menu.Item>
            </Menu.List>
          </Menu>
        </Sidebar.Body>
      </Sidebar>
    </>
  );
}
```

---

### Without Overlay

Sidebar without the background overlay.

:::caution
When `overlay={false}`, there's no backdrop to click for dismissal. Always provide an explicit Close action inside the sidebar (or rely on the Escape key) so users can close it.
:::

```tsx live
function example() {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <>
      <Button color="link" onClick={() => setIsOpen(true)}>
        Open Without Overlay
      </Button>
      <Paragraph mt="4">
        You can still interact with the page content when the sidebar is open.
      </Paragraph>
      <Sidebar
        inline
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        overlay={false}
      >
        <Sidebar.Header>
          <Sidebar.Title>No Overlay</Sidebar.Title>
          <Sidebar.Close onClick={() => setIsOpen(false)} />
        </Sidebar.Header>
        <Sidebar.Body>
          <Menu>
            <Menu.List>
              <Menu.Item href="#">Home</Menu.Item>
              <Menu.Item href="#">About</Menu.Item>
              <Menu.Item href="#">Contact</Menu.Item>
            </Menu.List>
          </Menu>
          <Button color="primary" mt="4" onClick={() => setIsOpen(false)}>
            Close Sidebar
          </Button>
        </Sidebar.Body>
      </Sidebar>
    </>
  );
}
```

---

### Non-cancelable Sidebar

Sidebar that cannot be dismissed by overlay click or escape key.

```tsx live
function example() {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <>
      <Button color="danger" onClick={() => setIsOpen(true)}>
        Open Important Panel
      </Button>
      <Sidebar
        inline
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        overlayClose={false}
        escapeClose={false}
        canCancel={false}
      >
        <Sidebar.Header>
          <Sidebar.Title>Important Action</Sidebar.Title>
        </Sidebar.Header>
        <Sidebar.Body>
          <Paragraph>You must complete this action before closing.</Paragraph>
          <Button color="primary" onClick={() => setIsOpen(false)} mt="4">
            Complete & Close
          </Button>
        </Sidebar.Body>
      </Sidebar>
    </>
  );
}
```

---

### Sidebar with Footer

Use `Sidebar.Footer` for actions or metadata pinned to the bottom of the sidebar.

```tsx live
function example() {
  const [isOpen, setIsOpen] = useState(false);
  return (
    <>
      <Button color="primary" onClick={() => setIsOpen(true)}>
        Open With Footer
      </Button>
      <Sidebar inline isOpen={isOpen} onClose={() => setIsOpen(false)}>
        <Sidebar.Header>
          <Sidebar.Title>Navigation</Sidebar.Title>
          <Sidebar.Close onClick={() => setIsOpen(false)} />
        </Sidebar.Header>
        <Sidebar.Body>
          <Menu>
            <Menu.Label>Pages</Menu.Label>
            <Menu.List>
              <Menu.Item active href="#">
                Home
              </Menu.Item>
              <Menu.Item href="#">Products</Menu.Item>
              <Menu.Item href="#">Services</Menu.Item>
              <Menu.Item href="#">Blog</Menu.Item>
              <Menu.Item href="#">Contact</Menu.Item>
            </Menu.List>
          </Menu>
        </Sidebar.Body>
        <Sidebar.Footer>
          <Paragraph textSize="7" textColor="grey">
            © 2026 Company Name
          </Paragraph>
        </Sidebar.Footer>
      </Sidebar>
    </>
  );
}
```

---

## Close Methods

When `canCancel` is true, the sidebar can be closed by:

1. **Clicking the overlay** - When `overlayClose` is true
2. **Pressing Escape key** - When `escapeClose` is true
3. **Calling `onClose`** - From a button or other action

---

## Accessibility

- Uses `role="dialog"` for proper screen reader announcement
- Has `aria-modal="true"` when overlay is shown
- Focus is trapped within the sidebar when open
- Escape key closes the sidebar by default
- Body scroll is prevented when sidebar is open

---

## Related Components

- [Modal](./modal.md) - For centered modal dialogs
- [Menu](./menu.md) - For navigation menus inside sidebar

---

## Additional Resources

- [Storybook: Sidebar Stories](https://bestax.io/storybook/?path=/story/components-sidebar)

:::tip Pro Tip
Use the Sidebar with a Menu component for building navigation drawers in mobile-responsive layouts.
:::

---

## Steps


## Overview

The `Steps` component provides a multi-step progress indicator for wizard flows, checkout processes, or any multi-step workflow. It supports horizontal and vertical layouts, customizable markers, and clickable navigation.

---

## Import

```tsx

```

---

## Props

| Prop              | Type                                                                            | Default    | Description                                      |
| ----------------- | ------------------------------------------------------------------------------- | ---------- | ------------------------------------------------ |
| `value`           | `number`                                                                        | `0`        | Current active step (0-indexed).                 |
| `items`           | `StepItemProps[]`                                                               | —          | Array of step items.                             |
| `size`            | `'small'` \| `'medium'` \| `'large'`                                            | —          | Size of the steps.                               |
| `color`           | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` | —          | Color variant.                                   |
| `hasMarker`       | `boolean`                                                                       | `true`     | Show step markers.                               |
| `animated`        | `boolean`                                                                       | `true`     | Enable animations.                               |
| `rounded`         | `boolean`                                                                       | `true`     | Use rounded markers.                             |
| `vertical`        | `boolean`                                                                       | `false`    | Vertical layout.                                 |
| `labelPosition`   | `'bottom'` \| `'right'` \| `'left'`                                             | `'bottom'` | Position of labels.                              |
| `mobileMode`      | `'minimal'` \| `'compact'` \| `'right'`                                         | —          | Mobile display mode.                             |
| `onStepClick`     | `(step: number) => void`                                                        | —          | Callback when a step is clicked.                 |
| `showStepNumbers` | `boolean`                                                                       | `true`     | Displays step numbers in the markers.            |
| `hasNavigation`   | `boolean`                                                                       | `false`    | Shows previous/next navigation buttons.          |
| `prevLabel`       | `string`                                                                        | —          | Label for the previous button.                   |
| `nextLabel`       | `string`                                                                        | —          | Label for the next button.                       |
| `onPrev`          | `() => void`                                                                    | —          | Callback when previous button is clicked.        |
| `onNext`          | `() => void`                                                                    | —          | Callback when next button is clicked.            |
| `children`        | `React.ReactNode`                                                               | —          | Step children (alternative to items).            |
| `className`       | `string`                                                                        | —          | Additional CSS classes.                          |
| ...               | All standard HTML and Bulma helper props                                        |            | (See [Helper Props](../helpers/usebulmaclasses)) |

### StepItemProps

| Prop            | Type              | Default | Description                            |
| --------------- | ----------------- | ------- | -------------------------------------- |
| `label`         | `React.ReactNode` | —       | Step label/title.                      |
| `icon`          | `React.ReactNode` | —       | Icon for the step marker.              |
| `clickable`     | `boolean`         | `false` | Whether this step is clickable.        |
| `completedIcon` | `React.ReactNode` | `'✓'`   | Icon shown when the step is completed. |
| `className`     | `string`          | —       | Additional class for this step.        |

---

## Usage

### Basic Steps

A simple step indicator showing progress through a flow.

```tsx live
<Steps
  value={1}
  items={[{ label: 'Account' }, { label: 'Profile' }, { label: 'Complete' }]}
/>
```

---

### Clickable Steps

Steps that allow navigation by clicking.

```tsx live
function example() {
  const [step, setStep] = useState(1);
  return (
    <Block>
      <Steps
        value={step}
        items={[
          { label: 'Account', clickable: true },
          { label: 'Profile', clickable: true },
          { label: 'Review', clickable: true },
          { label: 'Complete', clickable: true },
        ]}
        onStepClick={setStep}
        color="primary"
      />
      <Paragraph mt="4">Current step: {step + 1}</Paragraph>
    </Block>
  );
}
```

---

### Color Variants

Steps with different color variants.

```tsx live
<Block display="flex" flexDirection="column" gap="5">
  <Steps
    value={1}
    color="primary"
    items={[{ label: 'Step 1' }, { label: 'Step 2' }, { label: 'Step 3' }]}
  />
  <Steps
    value={1}
    color="success"
    items={[{ label: 'Step 1' }, { label: 'Step 2' }, { label: 'Step 3' }]}
  />
  <Steps
    value={1}
    color="info"
    items={[{ label: 'Step 1' }, { label: 'Step 2' }, { label: 'Step 3' }]}
  />
  <Steps
    value={1}
    color="warning"
    items={[{ label: 'Step 1' }, { label: 'Step 2' }, { label: 'Step 3' }]}
  />
  <Steps
    value={1}
    color="danger"
    items={[{ label: 'Step 1' }, { label: 'Step 2' }, { label: 'Step 3' }]}
  />
</Block>
```

---

### Size Variants

Steps with different size variants.

```tsx live
<Block display="flex" flexDirection="column" gap="5">
  <Steps
    value={1}
    size="small"
    items={[{ label: 'Step 1' }, { label: 'Step 2' }, { label: 'Step 3' }]}
  />
  <Steps
    value={1}
    items={[{ label: 'Step 1' }, { label: 'Step 2' }, { label: 'Step 3' }]}
  />
  <Steps
    value={1}
    size="medium"
    items={[{ label: 'Step 1' }, { label: 'Step 2' }, { label: 'Step 3' }]}
  />
  <Steps
    value={1}
    size="large"
    items={[{ label: 'Step 1' }, { label: 'Step 2' }, { label: 'Step 3' }]}
  />
</Block>
```

---

### With Icons

Steps with custom icons in markers.

```tsx live
<Steps
  value={1}
  color="info"
  items={[
    { label: 'Cart', icon: <Icon name="shopping-cart" variant="solid" /> },
    { label: 'Shipping', icon: <Icon name="truck" variant="solid" /> },
    { label: 'Payment', icon: <Icon name="credit-card" variant="solid" /> },
    { label: 'Done', icon: <Icon name="check" variant="solid" /> },
  ]}
/>
```

---

### Vertical Layout

Steps in vertical orientation.

```tsx live
<Steps
  value={1}
  vertical
  color="primary"
  items={[
    { label: 'Create Account' },
    { label: 'Set Up Profile' },
    { label: 'Choose Plan' },
    { label: 'Start Using' },
  ]}
/>
```

---

### Rounded Markers

Steps with rounded (circular) markers.

```tsx live
<Steps
  value={2}
  rounded
  color="success"
  items={[
    { label: 'Order Placed' },
    { label: 'Processing' },
    { label: 'Shipped' },
    { label: 'Delivered' },
  ]}
/>
```

---

### Checkout Flow Example

A complete checkout flow with navigation buttons.

```tsx live
function example() {
  const [step, setStep] = useState(0);
  const steps = ['Cart', 'Shipping', 'Payment', 'Confirm'];

  return (
    <Block>
      <Steps
        value={step}
        items={steps.map((label, i) => ({ label, clickable: i <= step }))}
        onStepClick={s => s <= step && setStep(s)}
        color="primary"
      />
      <Box mt="4" p="4">
        <Title size="5">{steps[step]}</Title>
        <Paragraph>Content for the {steps[step]} step goes here.</Paragraph>
      </Box>
      <Buttons mt="4">
        <Button
          onClick={() => setStep(Math.max(0, step - 1))}
          disabled={step === 0}
        >
          Previous
        </Button>
        <Button
          color="primary"
          onClick={() => setStep(Math.min(3, step + 1))}
          disabled={step === 3}
        >
          {step === 2 ? 'Place Order' : 'Next'}
        </Button>
      </Buttons>
    </Block>
  );
}
```

---

## Accessibility

- Steps use `aria-current="step"` on the active step
- Clickable steps are keyboard navigable with proper focus indicators
- Use descriptive labels for each step
- The step markers show completion state with checkmarks

---

## Related Components

- [Progress](../elements/progress.md) - For linear progress indication

---

## Additional Resources

- [Storybook: Steps Stories](https://bestax.io/storybook/?path=/story/components-steps)

:::tip Pro Tip
Use the `onStepClick` callback with `clickable: true` on items to allow users to navigate back to previous steps.
:::

---

## Tabs


## Overview

The `Tabs` component provides flexible and fully-featured Bulma tab navigation for your Bulma React UI. It supports alignment, size, color, boxed and toggle styles, rounded and fullwidth options, and can display icons or custom content in each tab. Compose tabs using the `Tabs.List` and `Tabs.Item` subcomponents for maximum flexibility.

:::info
Use `Tabs` for navigation, filtering, or switching between views. Combine with icons and Bulma helpers for advanced layouts.
:::

---

## Import

```tsx

```

---

## Props

| Prop           | Type                                                | Default | Description                                             |
| -------------- | --------------------------------------------------- | ------- | ------------------------------------------------------- |
| `value`        | `number`                                            | —       | Controlled active tab index.                            |
| `defaultValue` | `number`                                            | `0`     | Initial active tab index (uncontrolled).                |
| `onChange`     | `(index: number) => void`                           | —       | Callback when active tab changes.                       |
| `align`        | `'centered'` \| `'right'` \| `'left'`               | —       | Tab alignment.                                          |
| `size`         | `'small'` \| `'medium'` \| `'large'`                | —       | Tab size.                                               |
| `fullwidth`    | `boolean`                                           | `false` | Tabs expand to fill the horizontal space.               |
| `expanded`     | `boolean`                                           | —       | Makes tabs take up the full width equally.              |
| `boxed`        | `boolean`                                           | `false` | Tabs use the boxed style.                               |
| `toggle`       | `boolean`                                           | `false` | Tabs use the toggle style.                              |
| `rounded`      | `boolean`                                           | `false` | Tabs use the rounded toggle style (only with `toggle`). |
| `vertical`     | `boolean`                                           | —       | Renders tabs vertically.                                |
| `side`         | `'left'` \| `'right'`                               | —       | Side placement when `vertical` is true.                 |
| `color`        | Bulma color (`'primary'`, `'link'`, `'info'`, etc.) | —       | Bulma color for tab underlines and active state.        |
| `className`    | `string`                                            | —       | Additional CSS classes.                                 |
| `children`     | `React.ReactNode`                                   | —       | Tab list and tab items.                                 |
| ...            | All standard HTML and Bulma helper props            |         | (See [Helper Props](../helpers/usebulmaclasses))        |

**Subcomponents:**

- `Tabs.List`: The `` container for tab items.
- `Tabs.Item`: Each tab; accepts `active`, `onClick`, etc.

### Tabs.Tab

| Prop           | Type                                                               | Default   | Description                                        |
| -------------- | ------------------------------------------------------------------ | --------- | -------------------------------------------------- |
| `index`        | `number`                                                           | —         | **Required.** Tab index for matching with content. |
| `disabled`     | `boolean`                                                          | —         | Disables the tab.                                  |
| `icon`         | `string`                                                           | —         | Icon name for the tab.                             |
| `iconLibrary`  | `'fa' \| 'mdi' \| 'ion' \| 'material-icons' \| 'material-symbols'` | —         | Icon library to use.                               |
| `iconVariant`  | `string`                                                           | —         | Icon style variant.                                |
| `iconSize`     | `'small' \| 'medium' \| 'large'`                                   | `'small'` | Size of the tab icon.                              |
| `iconFeatures` | `string \| string[]`                                               | —         | Additional icon modifiers.                         |
| `children`     | `React.ReactNode`                                                  | —         | Tab label content.                                 |

### Tabs.Content

Container for tab content panels. No custom props beyond `children` and standard `` HTML attributes.

### Tabs.Content.Item

| Prop       | Type              | Default | Description                                                              |
| ---------- | ----------------- | ------- | ------------------------------------------------------------------------ |
| `index`    | `number`          | —       | **Required.** Content index matching the corresponding `Tabs.Tab` index. |
| `children` | `React.ReactNode` | —       | Content for this tab panel.                                              |

---

## Usage

### Centered Alignment

This example demonstrates a tab navigation with centered alignment using the `align="centered"` prop. Compose your tabs with `Tabs.List` and `Tabs.Item`, and use the `active` prop to highlight the selected tab. This layout is ideal for main navigation or switching between views.

```tsx live
<Tabs align="centered">
  <Tabs.List>
    <Tabs.Item active>
      Home
    </Tabs.Item>
    <Tabs.Item>
      Profile
    </Tabs.Item>
    <Tabs.Item>
      Settings
    </Tabs.Item>
  </Tabs.List>
</Tabs>
```

---

### Right Alignment

This example shows how to align tabs to the right using the `align="right"` prop. The `active` prop marks the current tab, and you can add as many `Tabs.Item` components as needed for your navigation structure.

```tsx live
<Tabs align="right">
  <Tabs.List>
    <Tabs.Item>
      Home
    </Tabs.Item>
    <Tabs.Item active>
      Profile
    </Tabs.Item>
    <Tabs.Item>
      Settings
    </Tabs.Item>
  </Tabs.List>
</Tabs>
```

---

### With Icons

This example demonstrates using icons in your tabs. Each tab can contain an icon and text, making your navigation more visually appealing and informative. The `active` tab is highlighted, and you can use any Font Awesome icons or your custom icons.

```tsx live
<Tabs>
  <Tabs.List>
    <Tabs.Item active>
      
        <Icon name="fas fa-image" size="small" />
        Pictures
      
    </Tabs.Item>
    <Tabs.Item>
      
        <Icon name="fas fa-music" size="small" />
        Music
      
    </Tabs.Item>
    <Tabs.Item>
      
        <Icon name="fas fa-film" size="small" />
        Videos
      
    </Tabs.Item>
    <Tabs.Item>
      
        <Icon name="fas fa-file-alt" size="small" />
        Documents
      
    </Tabs.Item>
  </Tabs.List>
</Tabs>
```

---

### Small, Medium, and Large Tabs

Easily adjust the size of your tabs using the `size` prop. This example shows the three available sizes: small, medium, and large. Each size variation can be used to emphasize different levels of navigation or to fit different design requirements.

```tsx live
<>
  <Tabs size="small">
    <Tabs.List>
      <Tabs.Item active>
        Tab 1
      </Tabs.Item>
      <Tabs.Item>
        Tab 2
      </Tabs.Item>
      <Tabs.Item>
        Tab 3
      </Tabs.Item>
    </Tabs.List>
  </Tabs>

  <Tabs size="medium">
    <Tabs.List>
      <Tabs.Item active>
        Tab 1
      </Tabs.Item>
      <Tabs.Item>
        Tab 2
      </Tabs.Item>
      <Tabs.Item>
        Tab 3
      </Tabs.Item>
    </Tabs.List>
  </Tabs>

  <Tabs size="large">
    <Tabs.List>
      <Tabs.Item active>
        Tab 1
      </Tabs.Item>
      <Tabs.Item>
        Tab 2
      </Tabs.Item>
      <Tabs.Item>
        Tab 3
      </Tabs.Item>
    </Tabs.List>
  </Tabs>
</>
```

---

### Boxed Tabs

The boxed style gives your tabs a distinct, separated look. This example demonstrates how to create boxed tabs using the `boxed` prop. Boxed tabs are great for categorizing content or features distinctly.

```tsx live
<Tabs boxed>
  <Tabs.List>
    <Tabs.Item active>
      Overview
    </Tabs.Item>
    <Tabs.Item>
      Elements
    </Tabs.Item>
    <Tabs.Item>
      Components
    </Tabs.Item>
  </Tabs.List>
</Tabs>
```

---

### Toggle Tabs

Toggle tabs are useful for binary views or filters, such as showing all items versus only active items. This example shows how to create toggle tabs using the `toggle` prop. The active tab indicates the current filter or view.

```tsx live
<Tabs toggle>
  <Tabs.List>
    <Tabs.Item active>
      All
    </Tabs.Item>
    <Tabs.Item>
      Active
    </Tabs.Item>
    <Tabs.Item>
      Completed
    </Tabs.Item>
  </Tabs.List>
</Tabs>
```

---

### Toggle Rounded Tabs

Combine the toggle style with rounded corners for a pill-like appearance. This example demonstrates toggle rounded tabs, which are especially useful in mobile interfaces or where a softer look is desired.

```tsx live
<Tabs toggle rounded>
  <Tabs.List>
    <Tabs.Item active>
      All
    </Tabs.Item>
    <Tabs.Item>
      Active
    </Tabs.Item>
    <Tabs.Item>
      Completed
    </Tabs.Item>
  </Tabs.List>
</Tabs>
```

---

### Fullwidth Tabs

Make your tabs span the entire width of their container with the `fullwidth` prop. This example shows fullwidth tabs, which are useful for emphasizing the tab navigation or when you have many tabs to display.

```tsx live
<Tabs fullwidth>
  <Tabs.List>
    <Tabs.Item active>
      One
    </Tabs.Item>
    <Tabs.Item>
      Two
    </Tabs.Item>
    <Tabs.Item>
      Three
    </Tabs.Item>
    <Tabs.Item>
      Four
    </Tabs.Item>
  </Tabs.List>
</Tabs>
```

---

### Centered Boxed Tabs with Icons

This example combines several features: centered alignment, boxed style, and icons. Such a combination is perfect for a dashboard or a complex application where you need to save space and still provide clear navigation.

```tsx live
<Tabs align="centered" boxed>
  <Tabs.List>
    <Tabs.Item active>
      
        <Icon name="fas fa-home" size="small" />
        Home
      
    </Tabs.Item>
    <Tabs.Item>
      
        <Icon name="fas fa-user" size="small" />
        Profile
      
    </Tabs.Item>
    <Tabs.Item>
      
        <Icon name="fas fa-cog" size="small" />
        Settings
      
    </Tabs.Item>
  </Tabs.List>
</Tabs>
```

---

### Toggle Fullwidth Tabs with Icons

Enhance your toggle tabs with icons for better visual communication. This example also uses the `fullwidth` prop to make the tabs span the entire width, which is useful for mobile views or when you want to emphasize the tab bar.

```tsx live
<Tabs toggle fullwidth>
  <Tabs.List>
    <Tabs.Item active>
      
        <Icon name="fas fa-list" size="small" />
        List
      
    </Tabs.Item>
    <Tabs.Item>
      
        <Icon name="fas fa-check" size="small" />
        Done
      
    </Tabs.Item>
    <Tabs.Item>
      
        <Icon name="fas fa-times" size="small" />
        Removed
      
    </Tabs.Item>
  </Tabs.List>
</Tabs>
```

---

### Centered Boxed Medium Tabs with Icons

This example features centered, boxed tabs in medium size, each with an icon. It's a great layout for a feature-rich application where you want to provide quick access to important sections.

```tsx live
<Tabs align="centered" boxed size="medium">
  <Tabs.List>
    <Tabs.Item active>
      
        <Icon name="fas fa-star" size="small" />
        Favorites
      
    </Tabs.Item>
    <Tabs.Item>
      
        <Icon name="fas fa-clock" size="small" />
        Recent
      
    </Tabs.Item>
    <Tabs.Item>
      
        <Icon name="fas fa-archive" size="small" />
        Archive
      
    </Tabs.Item>
  </Tabs.List>
</Tabs>
```

---

### Toggle Fullwidth Large Tabs with Icons

The final example showcases toggle tabs with fullwidth and large size, including icons. This combination is powerful for applications with complex navigation needs, ensuring that users can easily understand and access different sections.

```tsx live
<Tabs toggle fullwidth size="large">
  <Tabs.List>
    <Tabs.Item active>
      
        <Icon name="fas fa-rocket" size="small" />
        Launch
      
    </Tabs.Item>
    <Tabs.Item>
      
        <Icon name="fas fa-bell" size="small" />
        Alerts
      
    </Tabs.Item>
    <Tabs.Item>
      
        <Icon name="fas fa-cogs" size="small" />
        Settings
      
    </Tabs.Item>
  </Tabs.List>
</Tabs>
```

---

## Accessibility

- The tab list renders as a semantic `` and each item as ``.
- Use clear text or icons with labels for each tab.
- Provide `aria-label` or screen-reader text for icon-only tabs.

:::note
Tabs do not manage tab panels or keyboard focus automatically—implement those patterns as needed for your app.
:::

---

## Related Components

- [`Icon`](../elements/icon.md): Use for icons in tab labels.
- [Helper Props](../helpers/usebulmaclasses.md): All Bulma utility helpers are supported.

---

## Additional Resources

- [Bulma Tabs Documentation](https://bulma.io/documentation/components/tabs/)
- [Storybook: Tabs Stories](https://bestax.io/storybook/?path=/story/components-tabs--alignment-centered)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Tabs />` and its subcomponents for powerful utility-based styling.
:::

---

## Toast


## Overview

The `Toast` component provides brief notification messages with optional action and cancel buttons. Toasts are non-blocking and ideal for success messages, warnings, undo prompts, or general feedback.

---

## Import

```tsx

```

---

## Props

| Prop           | Type                                                                                                        | Default       | Description                                                |
| -------------- | ----------------------------------------------------------------------------------------------------------- | ------------- | ---------------------------------------------------------- |
| `message`      | `string`                                                                                                    | —             | The message to display (required).                         |
| `type`         | `'default'` \| `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`              | `'default'`   | Color variant — colors the toast **background**.           |
| `actionType`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`                             | —             | Color variant — colors the **action button** text.         |
| `position`     | `'top-right'` \| `'top-left'` \| `'top-center'` \| `'bottom-right'` \| `'bottom-left'` \| `'bottom-center'` | `'top-right'` | Position on the screen.                                    |
| `duration`     | `number`                                                                                                    | `2000`        | Duration in ms before auto-close. `0` disables auto-close. |
| `indefinite`   | `boolean`                                                                                                   | `false`       | Keeps the toast visible until dismissed.                   |
| `dismissible`  | `boolean`                                                                                                   | `true`        | Whether clicking the toast (or outside it) dismisses it.   |
| `closable`     | `boolean`                                                                                                   | `false`       | Show an explicit close (X) button.                         |
| `pauseOnHover` | `boolean`                                                                                                   | `false`       | Pause auto-close timer on hover.                           |
| `cancelable`   | `boolean`                                                                                                   | `true`        | Whether the toast can be dismissed with Escape.            |
| `actionText`   | `string`                                                                                                    | —             | Text for an action button (e.g. "Undo").                   |
| `cancelText`   | `string`                                                                                                    | —             | Text for a cancel button.                                  |
| `onAction`     | `() => void`                                                                                                | —             | Callback when the action button is clicked.                |
| `onClose`      | `() => void`                                                                                                | —             | Callback when toast closes.                                |
| `rounded`      | `boolean`                                                                                                   | `false`       | Pill-shaped (rounded corners).                             |
| `container`    | `string \| HTMLElement`                                                                                     | —             | CSS selector or DOM node to mount the toast into.          |
| `inline`       | `boolean`                                                                                                   | `false`       | Renders inline instead of using a portal.                  |
| `className`    | `string`                                                                                                    | —             | Additional CSS classes.                                    |
| `ref`          | `React.Ref<HTMLDivElement>`                                                                                 | —             | Ref forwarded to the toast element.                        |
| ...            | All standard HTML and Bulma helper props                                                                    |               | (See [Helper Props](../helpers/usebulmaclasses))           |

---

## Usage

:::tip Live Preview Only
The `inline` prop in the examples below is only there to render the toast inside the docs preview's shadow DOM. **Do not copy `inline`** — in your app, omit it and `Toast` will portal to `document.body` and float over the page automatically.
:::

### Basic Toast

A simple toast notification.

```tsx live
function example() {
  const [showToast, setShowToast] = useState(false);
  return (
    <Block>
      <Button color="primary" onClick={() => setShowToast(true)}>
        Show Toast
      </Button>
      {showToast && (
        <Toast
          inline
          message="This is a notification message!"
          duration={0}
          onClose={() => setShowToast(false)}
        />
      )}
    </Block>
  );
}
```

---

### Toast Types

`type` colors the toast background.

```tsx live
function example() {
  const [toastType, setToastType] = useState(null);
  return (
    <Block>
      <Buttons>
        <Button color="success" onClick={() => setToastType('success')}>
          Success
        </Button>
        <Button color="danger" onClick={() => setToastType('danger')}>
          Danger
        </Button>
        <Button color="warning" onClick={() => setToastType('warning')}>
          Warning
        </Button>
        <Button color="info" onClick={() => setToastType('info')}>
          Info
        </Button>
      </Buttons>
      {toastType && (
        <Toast
          inline
          message={`This is a ${toastType} message!`}
          type={toastType}
          duration={0}
          onClose={() => setToastType(null)}
        />
      )}
    </Block>
  );
}
```

---

### Toast Positions

Toast can appear in any of six positions. (The `transform` on the wrapper is a docs-only trick that scopes the toast's `position: fixed` to the example box; in your app, omit the wrapper.)

```tsx live
function example() {
  const [position, setPosition] = useState(null);
  const [box, setBox] = useState(null);
  return (
    
      <Buttons>
        <Button onClick={() => setPosition('top-left')}>Top Left</Button>
        <Button onClick={() => setPosition('top-center')}>Top Center</Button>
        <Button onClick={() => setPosition('top-right')}>Top Right</Button>
      </Buttons>
      <Buttons>
        <Button onClick={() => setPosition('bottom-left')}>Bottom Left</Button>
        <Button onClick={() => setPosition('bottom-center')}>
          Bottom Center
        </Button>
        <Button onClick={() => setPosition('bottom-right')}>
          Bottom Right
        </Button>
      </Buttons>
      {position && box && (
        <Toast
          container={box}
          message={`Position: ${position}`}
          position={position}
          type="info"
          duration={0}
          onClose={() => setPosition(null)}
        />
      )}
    
  );
}
```

---

### Action Button

Add an action button (e.g. "Undo"). `actionType` colors the action button text.

```tsx live
function example() {
  const [showToast, setShowToast] = useState(false);
  return (
    <Block>
      <Button color="primary" onClick={() => setShowToast(true)}>
        Show Toast with Action
      </Button>
      {showToast && (
        <Toast
          inline
          message="Item deleted"
          actionText="Undo"
          actionType="info"
          onAction={() => alert('Undone!')}
          duration={0}
          onClose={() => setShowToast(false)}
        />
      )}
    </Block>
  );
}
```

---

### Cancel + Action Buttons

Combine cancel and action buttons for a confirm-style toast.

```tsx live
function example() {
  const [showToast, setShowToast] = useState(false);
  return (
    <Block>
      <Button color="primary" onClick={() => setShowToast(true)}>
        Show Confirm Toast
      </Button>
      {showToast && (
        <Toast
          inline
          message="Are you sure you want to proceed?"
          cancelText="Cancel"
          actionText="Confirm"
          actionType="danger"
          duration={0}
          onAction={() => alert('Confirmed!')}
          onClose={() => setShowToast(false)}
        />
      )}
    </Block>
  );
}
```

---

### Closable

Show an explicit close (X) button alongside the message.

```tsx live
function example() {
  const [showToast, setShowToast] = useState(false);
  return (
    <Block>
      <Button color="primary" onClick={() => setShowToast(true)}>
        Show Closable Toast
      </Button>
      {showToast && (
        <Toast
          inline
          message="This toast has a close button"
          closable
          duration={0}
          onClose={() => setShowToast(false)}
        />
      )}
    </Block>
  );
}
```

---

### Indefinite

Stay open until the user dismisses it.

```tsx live
function example() {
  const [showToast, setShowToast] = useState(false);
  return (
    <Block>
      <Button onClick={() => setShowToast(true)}>Show Indefinite Toast</Button>
      {showToast && (
        <Toast
          inline
          message="This won't auto-dismiss"
          indefinite
          onClose={() => setShowToast(false)}
        />
      )}
    </Block>
  );
}
```

---

## Programmatic API

For showing toasts from anywhere in your app, use the programmatic API.

### Setup

Add the `ToastContainer` once at your app root:

```tsx title="src/App.tsx"

function App() {
  return (
    <>
      <YourRoutes />
      <ToastContainer position="top-right" />
    </>
  );
}
```

### API Methods

```tsx

// Show different toast types
toast.success('Operation successful!');
toast.danger('Something went wrong');
toast.warning('Please review your changes');
toast.info('New message received');

// Show with options
toast.show({
  message: 'Custom toast',
  type: 'primary',
  duration: 5000,
  position: 'bottom-center',
});

// Show with action
toast.show({
  message: 'File moved to trash',
  actionText: 'Undo',
  actionType: 'info',
  onAction: () => restoreFile(),
});

// Queued toasts display one at a time (FIFO)
toast.show({ message: 'Step 1', queue: true });
toast.show({ message: 'Step 2', queue: true });

// Close specific toast
const id = toast.success('Hello');
toast.close(id);

// Close all toasts
toast.closeAll();
```

---

## Accessibility

- Uses `role="alert"` for screen reader announcement.
- Has `aria-live="polite"` for non-intrusive notifications.
- The closable button has `aria-label="Close"`.
- `pauseOnHover` lets users keep the toast visible while reading.
- `cancelable` (default `true`) supports Escape-key dismiss.

---

## Related Components

- [Dialog](./dialog.md) - For confirmation dialogs.

---

## Additional Resources

- [Storybook: Toast Stories](https://bestax.io/storybook/?path=/story/components-toast)

:::tip Pro Tip
Use the programmatic `toast` API for showing notifications from event handlers or async operations without managing state.
:::

---

## Tooltip


## Overview

The `Tooltip` component displays helpful information when users hover over or focus on an element. It supports multiple positions, colors, and styles. Perfect for providing additional context, abbreviation expansions, or action descriptions.

---

## Import

```tsx

```

---

## Props

| Prop               | Type                                                                                                     | Default | Description                                      |
| ------------------ | -------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `label`            | `string`                                                                                                 | —       | The tooltip text content.                        |
| `position`         | `'top'` \| `'bottom'` \| `'left'` \| `'right'` \| `'auto'`                                               | `'top'` | Position of the tooltip.                         |
| `color`            | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'dark'` \| `'light'` | —       | Color variant.                                   |
| `active`           | `boolean`                                                                                                | `false` | Force tooltip to be always visible.              |
| `multiline`        | `boolean`                                                                                                | `false` | Allow tooltip to wrap to multiple lines.         |
| `animated`         | `boolean`                                                                                                | `true`  | Enable fade animation.                           |
| `square`           | `boolean`                                                                                                | `false` | Use square corners instead of rounded.           |
| `dashed`           | `boolean`                                                                                                | `false` | Show dashed underline on trigger.                |
| `delay`            | `number`                                                                                                 | `0`     | Delay before showing tooltip (ms).               |
| `children`         | `React.ReactNode`                                                                                        | —       | The element that triggers the tooltip.           |
| `className`        | `string`                                                                                                 | —       | Additional CSS classes.                          |
| `tooltipClassName` | `string`                                                                                                 | —       | Additional classes for the tooltip element.      |
| `content`          | `React.ReactNode`                                                                                        | —       | Rich tooltip content (alternative to `label`).   |
| `size`             | `'small'` \| `'medium'` \| `'large'`                                                                     | —       | Size of the tooltip.                             |
| `closeDelay`       | `number`                                                                                                 | `0`     | Delay in ms before hiding the tooltip.           |
| ...                | All standard HTML and Bulma helper props                                                                 |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Basic Tooltip

A simple tooltip on a button.

```tsx live
function example() {
  return (
    <Tooltip label="This is helpful information">
      <Button>Hover me</Button>
    </Tooltip>
  );
}
```

---

### Positions

Tooltip in different positions around the trigger.

```tsx live
function example() {
  return (
    <Buttons>
      <Tooltip label="Top tooltip" position="top">
        <Button>Top</Button>
      </Tooltip>
      <Tooltip label="Bottom tooltip" position="bottom">
        <Button>Bottom</Button>
      </Tooltip>
      <Tooltip label="Left tooltip" position="left">
        <Button>Left</Button>
      </Tooltip>
      <Tooltip label="Right tooltip" position="right">
        <Button>Right</Button>
      </Tooltip>
    </Buttons>
  );
}
```

---

### Colors

Tooltip with different color variants.

```tsx live
function example() {
  return (
    <Buttons>
      <Tooltip label="Primary" color="primary">
        <Button color="primary">Primary</Button>
      </Tooltip>
      <Tooltip label="Link" color="link">
        <Button color="link">Link</Button>
      </Tooltip>
      <Tooltip label="Info" color="info">
        <Button color="info">Info</Button>
      </Tooltip>
      <Tooltip label="Success" color="success">
        <Button color="success">Success</Button>
      </Tooltip>
      <Tooltip label="Warning" color="warning">
        <Button color="warning">Warning</Button>
      </Tooltip>
      <Tooltip label="Danger" color="danger">
        <Button color="danger">Danger</Button>
      </Tooltip>
    </Buttons>
  );
}
```

---

### Multiline

Tooltip that wraps to multiple lines for longer content.

```tsx live
function example() {
  return (
    <Block p="5">
      <Tooltip
        label="This is a longer tooltip that wraps to multiple lines. It's useful for displaying more detailed information."
        multiline
      >
        <Button>Hover for more info</Button>
      </Tooltip>
    </Block>
  );
}
```

---

### Always Visible

Tooltip that's always visible, regardless of hover state.

```tsx live
function example() {
  return (
    <Block p="5">
      <Tooltip label="I'm always visible!" active color="info">
        <Button>Always visible tooltip</Button>
      </Tooltip>
    </Block>
  );
}
```

---

### Dashed Underline

Tooltip on text with a dashed underline to indicate more info is available.

```tsx live
function example() {
  return (
    <Paragraph>
      The term{' '}
      <Tooltip label="Application Programming Interface" dashed>
        API
      </Tooltip>{' '}
      is commonly used in software development.
    </Paragraph>
  );
}
```

---

### With Delay

Tooltip that appears after a delay.

```tsx live
function example() {
  return (
    <Buttons>
      <Tooltip label="No delay" delay={0}>
        <Button>No delay</Button>
      </Tooltip>
      <Tooltip label="500ms delay" delay={500}>
        <Button>500ms delay</Button>
      </Tooltip>
      <Tooltip label="1 second delay" delay={1000}>
        <Button>1s delay</Button>
      </Tooltip>
    </Buttons>
  );
}
```

---

### On Icons

Tooltips on icon buttons for action descriptions.

```tsx live
function example() {
  return (
    <Block display="flex" gap="5" p="6">
      <Tooltip label="Delete item" color="danger" position="bottom">
        
          <Icon name="fas fa-trash" />
        
      </Tooltip>
      <Tooltip label="Edit item" color="info" position="bottom">
        
          <Icon name="fas fa-edit" />
        
      </Tooltip>
      <Tooltip label="Download" color="success" position="bottom">
        
          <Icon name="fas fa-download" />
        
      </Tooltip>
    </Block>
  );
}
```

---

### Form Field Help

Using tooltips to provide help for form fields.

```tsx live
function example() {
  return (
    <Field>
      <label className="label">
        Password{' '}
        <Tooltip
          label="Must be at least 8 characters with one number and one special character"
          multiline
          color="info"
        >
          
            <Icon name="fas fa-question-circle" size="small" />
          
        </Tooltip>
      </label>
      <Control>
        <Input type="password" placeholder="Enter password" />
      </Control>
    </Field>
  );
}
```

---

### Abbreviations

Using tooltips to explain abbreviations in text.

```tsx live
function example() {
  return (
    <Paragraph style={{ lineHeight: 1.8 }}>
      Hover over{' '}
      <Tooltip label="Cascading Style Sheets" color="info" dashed>
        CSS
      </Tooltip>{' '}
      or{' '}
      <Tooltip label="HyperText Markup Language" color="info" dashed>
        HTML
      </Tooltip>{' '}
      to see their full names.
    </Paragraph>
  );
}
```

---

## Accessibility

- Tooltip content has `role="tooltip"` for screen reader announcement
- Has `aria-hidden` that toggles based on visibility
- Tooltip shows on both hover and focus for keyboard users
- The `dashed` style provides a visual cue that more information is available

---

## Related

- [Icon](../elements/icon.md) - Icon component
- [Button](../elements/button.md) - Button component

---

## Block


## Overview

The `Block` component renders a simple container with Bulma's `.block` class, adding vertical margin between sections of content. Use it for grouping or spacing elements, especially in forms or stacked layouts. It supports all Bulma helper props for color, spacing, and more.

:::info
Bulma’s `.block` adds margin-bottom. For visual separation, combine with color or background helpers.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                               |
| `color`     | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`                                                                                                                                                                                                                    | —       | Bulma color modifier for the block.              |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Content to render inside the block.              |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                              |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Block

The default usage of the `Block` component creates a vertical space between content sections. Use this for separating paragraphs, images, or UI elements in your layout.

```tsx live
<Block>Default Block</Block>
```

### Primary Text Color

Set the text color using the `textColor` prop. For example, `textColor="primary"` applies Bulma's primary color to the text inside the block, making it stand out for emphasis or branding.

```tsx live
<Block textColor="primary">Block with Primary Text</Block>
```

### Light Background

Apply a background color using the `bgColor` prop. Here, `bgColor="light"` gives the block a subtle light background, making its content stand out from the rest of the page.

```tsx live
<Block bgColor="light">Block with Light Background</Block>
```

### Spacing and Alignment

You can use Bulma helper props like `m`, `p`, and `textAlign` to control margin, padding, and text alignment. This example centers the text and adds margin and padding for a visually balanced block.

```tsx live
<Block m="4" p="4" textAlign="centered">
  Block with Margin, Padding, and Centered Text
</Block>
```

### Custom Class

Add your own CSS classes with the `className` prop to further customize the block's appearance or behavior, such as adding custom backgrounds or effects.

```tsx live
<Block className="custom-block-class">Block with Custom Class</Block>
```

### Viewport-Specific Text Color

The `viewport` prop lets you apply color or other helpers at specific breakpoints. Here, `textColor="primary"` is only applied on tablet and larger screens, making the block adapt to different devices.

```tsx live
<Block textColor="primary" viewport="tablet">
  Block with Tablet-specific Primary Text
</Block>
```

### Interactive Block with Multiple Props

Combine multiple props such as `textColor`, `bgColor`, `m`, `p`, and `textAlign` to create visually distinct and interactive blocks for advanced layouts or callouts.

```tsx live
<Block textColor="success" bgColor="dark" m="3" p="3" textAlign="right">
  Interactive Block
</Block>
```

### Stacked Blocks (Demonstrating Vertical Spacing)

This example shows how stacking multiple `Block` components creates consistent vertical spacing between each section. The inner `Notification` components have `mb={0}` to highlight the spacing provided by `Block`.

:::note
The notification blocks have zero margin bottom assigned to illustrate the spacing the blocks provide.
:::

```tsx live
<Block display="flex" flexDirection="column" gap="0">
  <Block>
    <Notification color="primary" mb={0}>
      First Block
    </Notification>
  </Block>
  <Block>
    <Notification color="info" mb={0}>
      Second Block
    </Notification>
  </Block>
  <Block>
    <Notification color="success" mb={0}>
      Third Block
    </Notification>
  </Block>
  <Block>
    <Notification color="warning" mb={0}>
      Fourth Block
    </Notification>
  </Block>
</Block>
```

---

## Accessibility

- **Content:** Use semantic HTML inside `Block` for best accessibility.
- **Spacing:** The `.block` class is for layout only and does not affect accessibility.
- **Contrast:** Choose text and background colors for good readability.

:::info
Use `Block` for logical, visually separated sections of content.
:::

---

## Related Components

- [`Box`](./box.md): For bordered, padded containers.
- [`Content`](./content.md): For typographically styled rich content.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Block Documentation](https://bulma.io/documentation/elements/block/)
- [Storybook: Block Stories](https://bestax.io/storybook/?path=/story/elements-block--default)

---

## Box


## Overview

The `Box` component renders a bordered, padded container with an optional shadow using Bulma's `.box` class. It's useful for visually separating content, callouts, or emphasizing important UI elements. Supports all Bulma helper props for color, spacing, and more.

:::info
By default, `Box` includes a subtle shadow. You can disable the shadow with `hasShadow={false}`.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                               |
| `color`     | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`                                                                                                                                                                                                                    | —       | Bulma color modifier for the box.                |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| `hasShadow` | `boolean`                                                                                                                                                                                                                                                                                | `true`  | Whether the box has a shadow.                    |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Content to render inside the box.                |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                              |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Box

The default usage of the `Box` component creates a bordered, padded container with a subtle shadow. Use this for grouping related content, highlighting sections, or providing visual separation in your layout.

```tsx live
<Box>Default Box</Box>
```

### Primary Text Color

Set the text color using the `textColor` prop. For example, `textColor="primary"` applies Bulma's primary color to the text inside the box, making it stand out for emphasis or branding.

```tsx live
<Box textColor="primary">Box with Primary Text</Box>
```

### Light Background

Apply a background color using the `bgColor` prop. Here, `bgColor="grey-light"` gives the box a subtle light background, making its content stand out from the rest of the page.

```tsx live
<Box bgColor="grey-light">Box with Light Background</Box>
```

### No Shadow

Disable the default shadow using the `hasShadow={false}` prop. This is helpful when you want a flatter appearance or need to match a minimal design.

```tsx live
<Box hasShadow={false}>Box without Shadow</Box>
```

### Spacing and Alignment

You can use Bulma helper props like `m`, `p`, and `textAlign` to control margin, padding, and text alignment. This example centers the text and adds margin and padding for a visually balanced box.

```tsx live
<Box m="4" p="4" textAlign="centered">
  Box with Margin, Padding, and Centered Text
</Box>
```

### Custom Class

Add your own CSS classes with the `className` prop to further customize the box's appearance or behavior, such as adding custom backgrounds or effects.

```tsx live
<Box className="custom-box-class">Box with Custom Class</Box>
```

### Viewport-Specific Text Color

The `viewport` prop lets you apply color or other helpers at specific breakpoints. Here, `textColor="primary"` is only applied on tablet and larger screens, making the box adapt to different devices.

```tsx live
<Box textColor="primary" viewport="tablet">
  Box with Tablet-specific Primary Text
</Box>
```

### Interactive Box

Combine multiple props such as `textColor`, `bgColor`, `m`, `p`, and `textAlign` to create visually distinct and interactive boxes for advanced layouts or callouts.

```tsx live
<Box textColor="success" bgColor="black" m="3" p="3" textAlign="right">
  Interactive Box
</Box>
```

---

## Accessibility

- **Content:** Use semantic HTML inside `Box` for best accessibility.
- **Shadow:** The shadow is purely visual and does not affect accessibility.
- **Contrast:** Ensure color combinations provide sufficient contrast.

:::tip
`Box` is perfect for card-like containers, callouts, or visually separating content.
:::

---

## Related Components

- [`Block`](./block.md): For simple vertical spacing between blocks of content.
- [`Content`](./content.md): For typographically styled rich content.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Box Documentation](https://bulma.io/documentation/elements/box/)
- [Storybook: Box Stories](https://bestax.io/storybook/?path=/story/elements-box--default)

---

## Button


## Overview

The `Button` component provides a flexible and highly customizable button for your Bulma React UI. It supports all Bulma color, size, and state modifiers, as well as additional helper classes for text, spacing, and more.

:::tip
Make sure to provide meaningful text or accessible content for screen readers.
:::

---

## Import

```tsx

```

---

## Props

| Prop          | Type                                                                                                                                  | Description                                                                                                        |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `color`       | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'white' \| 'light' \| 'dark' \| 'black' \| 'text' \| 'ghost'` | Bulma color variant for the button. `ghost` renders a link-like button; `text` renders a minimal text-only button. |
| `size`        | `'small' \| 'normal' \| 'medium' \| 'large'`                                                                                          | Size of the button.                                                                                                |
| `isLight`     | `boolean`                                                                                                                             | Applies a lighter color variant.                                                                                   |
| `isRounded`   | `boolean`                                                                                                                             | Makes the button rounded.                                                                                          |
| `isLoading`   | `boolean`                                                                                                                             | Displays a loading spinner.                                                                                        |
| `isStatic`    | `boolean`                                                                                                                             | Makes the button non-interactive.                                                                                  |
| `isFullWidth` | `boolean`                                                                                                                             | Makes the button full-width.                                                                                       |
| `isOutlined`  | `boolean`                                                                                                                             | Applies outlined styling (requires color).                                                                         |
| `isInverted`  | `boolean`                                                                                                                             | Applies inverted styling (requires color).                                                                         |
| `isFocused`   | `boolean`                                                                                                                             | Applies focused styling (visual only).                                                                             |
| `isActive`    | `boolean`                                                                                                                             | Applies active styling (visual only).                                                                              |
| `isHovered`   | `boolean`                                                                                                                             | Applies hovered styling (visual only).                                                                             |
| `isDisabled`  | `boolean`                                                                                                                             | Applies disabled styling.                                                                                          |
| `as`          | `'button' \| 'a'`                                                                                                                     | Render as a `<button>` or ``.                                                                                   |
| `href`        | `string`                                                                                                                              | Href value (if rendering as ``).                                                                                |
| `onClick`     | `function`                                                                                                                            | Click event handler.                                                                                               |
| `target`      | `string`                                                                                                                              | Anchor tag target.                                                                                                 |
| `rel`         | `string`                                                                                                                              | Anchor tag rel.                                                                                                    |
| `textColor`   | `'primary'` \| ... (see docs)                                                                                                         | Text color helper.                                                                                                 |
| `bgColor`     | `'primary'` \| ... (see docs)                                                                                                         | Background color helper.                                                                                           |
| `className`   | `string`                                                                                                                              | Custom class name.                                                                                                 |
| `children`    | `React.ReactNode`                                                                                                                     | Button content.                                                                                                    |
| ...           | All standard `<button>` and Bulma helper props                                                                                        | See [Helper Props](../helpers/usebulmaclasses.md)                                                                  |

---

## Usage

### Default Button

This is the most fundamental use of the `Button` component, providing a simple yet stylish Bulma button for general actions. Use the default configuration (no extra props required) for forms, dialogs, toolbars, or anywhere you need a straightforward clickable action with Bulma’s default styling.

```tsx live
<Button>Default Button</Button>
```

### All Colors

By setting the `color` prop, you can style your button with any of Bulma's button colors. The semantic colors are `primary`, `link`, `info`, `success`, `warning`, and `danger`. Neutral colors are `white`, `light`, `dark`, and `black`. Special colors are `text` (minimal text-only button) and `ghost` (link-like button). This allows you to visually communicate the purpose of different actions—for example, use `success` for confirming, `danger` for destructive actions, or `ghost` for a button that looks like a link.

```tsx live

<Buttons>
  {['primary', 'link', 'info', 'success', 'warning', 'danger'].map(color => (
    <Button key={color} color={color}>
      {color.charAt(0).toUpperCase() + color.slice(1)}
    </Button>
  ))}
</Buttons>;
```

### All Sizes

The `size` prop lets you adjust the button’s scale for various contexts. Supported values for `size` are `small`, `normal`, `medium`, and `large`. Use `small` for compact UIs, `large` for important calls to action, and `normal` or `medium` for general use.

```tsx live
<Buttons>
  {['small', 'normal', 'medium', 'large'].map(size => (
    <Button key={size} size={size}>
      {size.charAt(0).toUpperCase() + size.slice(1)}
    </Button>
  ))}
</Buttons>
```

### Light Variant

Create a softer, pastel version of your button by adding the `isLight` prop. When combined with a `color`, such as `primary`, this produces a much lighter shade. This is useful for secondary actions or when you want your button to coordinate with your theme color without drawing too much attention.

```tsx live
<Button color="primary" isLight>
  Light Primary Button
</Button>
```

### Rounded

Enable the `isRounded` prop to give your button fully rounded edges. This style can help actions look friendlier and more approachable, and is often used in toolbars, cards, or to make special actions stand out visually.

```tsx live
<Button color="info" isRounded>
  Rounded Button
</Button>
```

### Loading

Set the `isLoading` prop to display a loading spinner inside the button. This is commonly used while waiting for an asynchronous operation, such as form submission or data fetching, providing user feedback and preventing multiple submissions. The button's content is replaced by the spinner while `isLoading` is active.

```tsx live
<Button color="success" isLoading>
  Loading Button
</Button>
```

### Static

When you need a button that looks interactive but isn’t clickable, use the `isStatic` prop. This makes the button non-interactive while retaining its visual appearance, which is useful for read-only forms, visual placeholders, or situations where you want to display a button-style element without enabling user actions.

```tsx live
<Button isStatic>Static Button</Button>
```

### Full Width

With the `isFullWidth` prop, your button will expand to completely fill the width of its parent container. This is useful for mobile layouts, modal footers, or anywhere you want your call-to-action to be easy to find and tap.

```tsx live
<Button color="warning" isFullWidth>
  Full Width Button
</Button>
```

### Outlined

Use the `isOutlined` prop to give your button a simple outlined style instead of a solid fill. This works in conjunction with the `color` prop and is ideal for secondary actions. The possible values for `color` here are the same as above: `primary`, `link`, `info`, `success`, `warning`, or `danger`.

```tsx live
<Button color="danger" isOutlined>
  Outlined Button
</Button>
```

### Inverted

The `isInverted` prop inverts the button’s color, making it suitable for placement on colored backgrounds. When paired with a `color` (such as `link`), it ensures the button maintains contrast and legibility regardless of the surrounding layout.

```tsx live
<Button color="link" isInverted>
  Inverted Button
</Button>
```

### Focused

Show a focused state by enabling the `isFocused` prop. This can help demonstrate keyboard navigation and accessibility features, as it visually marks which button is currently focused in the UI.

```tsx live
<Button color="primary" isFocused>
  Focused Button
</Button>
```

### Active

The `isActive` prop highlights the button as currently pressed or selected. This is useful in toggle groups, tab bars, or any situation where you need to indicate the active choice to your users.

```tsx live
<Button color="info" isActive>
  Active Button
</Button>
```

### Hovered

By setting the `isHovered` prop, you can force the button to display its hover style. This can be useful for UI previews, tutorials, or custom scenarios where you want to visually indicate what happens on mouseover, without requiring actual pointer interaction.

```tsx live
<Button color="success" isHovered>
  Hovered Button
</Button>
```

### Ghost

Use `color="ghost"` to render a button that looks like a link but behaves as a `<button>`. This is useful when you need an action trigger (not navigation) that visually blends with surrounding text, without resorting to a `` pattern.

```tsx live
<Button color="ghost">Ghost Button</Button>
```

### Text

Use `color="text"` to render a minimal text-only button with no background or border. This is ideal for subtle actions in toolbars or inline contexts where a standard button would be too prominent.

```tsx live
<Button color="text">Text Button</Button>
```

### Disabled

To make a button both visually and functionally inactive, use the `isDisabled` prop and add the native `disabled` attribute. This prevents all user interaction and applies appropriate styling and accessibility attributes, clearly communicating that the action is unavailable.

```tsx live
<Button color="warning" isDisabled disabled>
  Disabled Button
</Button>
```

### Custom Text and Background Color

With the `textColor` and `bgColor` props, you can independently set the button’s foreground and background colors. Accepted values for both are any Bulma color, such as `primary`, `info`, `danger`, etc. This approach lets you create unique, branded, or visually striking button styles beyond the defaults.

```tsx live
<Button textColor="danger" bgColor="info">
  Custom Text &amp; Background
</Button>
```

### Spacing Helpers

Add margin and padding to your button using Bulma’s spacing helper props: `m`, `p`, `mx`, `my`, `mt`, `mr`, `mb`, and `ml`. These accept numeric values (e.g., `2`, `4`), letting you fine-tune the space around your button directly from props, without custom CSS.

```tsx live
<Button m="2" p="3" mx="4" my="5" mt="1" mr="2" mb="3" ml="4">
  Button with Spacing
</Button>
```

### Text Alignment

Control the horizontal alignment of the button’s text using the `textAlign` prop. Possible values are `centered`, `justified`, `left`, and `right`. This is especially useful for full-width or toolbar buttons where text alignment matters for readability and style.

```tsx live
<Button textAlign="centered">Centered Text Button</Button>
```

### Responsive Viewport

The `viewport` prop allows you to apply responsive styles for specific breakpoints. Accepted values include `mobile`, `tablet`, `desktop`, `widescreen`, and `fullhd`. This makes it easy to tailor your button’s appearance for different devices and screen sizes.

```tsx live
<Button viewport="mobile">Mobile Responsive Button</Button>
```

### Flexbox Layout

Bulma’s flexbox helpers, like `display="flex"`, `justifyContent`, and `alignItems`, can be applied as props. For `justifyContent`, use `center`, `start`, `end`, `space-between`, `space-around`, or `space-evenly`; for `alignItems`, use `center`, `start`, `end`, `baseline`, or `stretch`. This lets you precisely control the layout of button content, such as centering icons and text.

```tsx live
<Button display="flex" justifyContent="center" alignItems="center">
  Flex Button
</Button>
```

### Button Group

Group multiple buttons together using the `<Buttons hasAddons>` component. The `hasAddons` prop ensures the buttons are visually connected, making it perfect for toolbars, segmented controls, or navigation layouts where related actions need to be grouped as a unit.

```tsx live
<Buttons hasAddons>
  <Button color="primary">Left</Button>
  <Button color="primary">Center</Button>
  <Button color="primary">Right</Button>
</Buttons>
```

### With HTML Attributes

You can pass any standard HTML attributes to the Button component, such as `type` (possible values: `button`, `submit`, or `reset`) and `className`. This ensures compatibility with forms, accessibility tooling, and integration with other React libraries.

```tsx live
<Button type="submit" className="custom-class">
  Submit Button
</Button>
```

---

## Accessibility

- **Labeling:** Always provide descriptive content for buttons for screen readers.
- **States:** The `isDisabled` and `disabled` props ensure correct `aria-disabled` and `disabled` attributes.
- **Keyboard:** When rendered as ``, disabled buttons are not focusable.
- **Focus:** Use `isFocused` and `isActive` for visual feedback, but rely on browser focus for actual accessibility.

:::note
If your button has only an icon, use `aria-label` to provide accessible text.
:::

---

## Related Components

- [`Buttons`](./buttons.md): Group multiple buttons together, including add-ons and alignment.
- [`Icon`](../elements/icon.md): Inline icons for use inside buttons.
- [Helper Props](../helpers/usebulmaclasses.md): List of all supported Bulma helper props for spacing, colors, etc.

---

## Additional Resources

- [Bulma Button Documentation](https://bulma.io/documentation/elements/button/)
- [React Button Accessibility](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
- [Storybook: Button Stories](https://bestax.io/storybook/?path=/story/elements-button--default)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Button />` for powerful utility-based styling.
:::

---

## Buttons


## Overview

The `Buttons` component lets you group multiple `Button` elements together with Bulma's spacing, alignment, and add-on features. It's ideal for toolbars, button clusters, or any UI where you want a consistent group of buttons, including add-on styling, centering, or right alignment.

:::tip
Use the `Buttons` component to maintain Bulma's consistent button group layout and spacing in your UI.
:::

---

## Import

```tsx

```

---

## Props

| Prop         | Type                                                                                                                                                                                                                                                                                     | Default | Description                                                      |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `className`  | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                                          |
| `textColor`  | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper for the button group.                          |
| `color`      | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`                                                                                                                                                                                                                    | —       | Bulma color modifier for the button group.                       |
| `bgColor`    | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper for the button group.                    |
| `isCentered` | `boolean`                                                                                                                                                                                                                                                                                | `false` | Center the group of buttons.                                     |
| `isRight`    | `boolean`                                                                                                                                                                                                                                                                                | `false` | Align the group of buttons to the right.                         |
| `hasAddons`  | `boolean`                                                                                                                                                                                                                                                                                | `false` | Group buttons together as addons (removes spacing between them). |
| `children`   | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | The button elements to render inside the group.                  |
| ...          | All standard `` and Bulma helper props                                                                                                                                                                                                                                              |         | (See [Helper Props](../helpers/usebulmaclasses))                 |

---

## Usage

### Default Button Group

The default usage of the `Buttons` component groups multiple `Button` elements together with consistent spacing. Use this for toolbars, button clusters, or any UI where you want a visually unified group of buttons.

```tsx live
<Buttons>
  <Button color="primary">Save</Button>
  <Button color="info">Edit</Button>
  <Button color="danger">Delete</Button>
</Buttons>
```

### All Colors Group

This example shows a group of buttons, each with a different `color` prop (`primary`, `link`, `info`, `success`, `warning`, `danger`). Use this to visually distinguish actions or statuses within a button group.

```tsx live
<Buttons>
  {['primary', 'link', 'info', 'success', 'warning', 'danger'].map(color => (
    <Button key={color} color={color}>
      {color.charAt(0).toUpperCase() + color.slice(1)}
    </Button>
  ))}
</Buttons>
```

### All Sizes Group

Demonstrates a group of buttons with different `size` props (`small`, `normal`, `medium`, `large`). Use this to show how button groups adapt to various sizing needs.

```tsx live
<Buttons>
  {['small', 'normal', 'medium', 'large'].map(size => (
    <Button key={size} size={size}>
      {size.charAt(0).toUpperCase() + size.slice(1)}
    </Button>
  ))}
</Buttons>
```

### Add-ons (No Spacing Between Buttons)

The `hasAddons` prop removes spacing between buttons, making them appear as a single connected group. This is useful for segmented controls or tightly grouped actions.

```tsx live
<Buttons hasAddons>
  <Button color="primary">Left</Button>
  <Button color="primary">Center</Button>
  <Button color="primary">Right</Button>
</Buttons>
```

### Centered Group

The `isCentered` prop centers the button group within its container. Use this for balanced layouts or when you want the group to stand out.

```tsx live
<Buttons isCentered>
  <Button color="info">One</Button>
  <Button color="info">Two</Button>
</Buttons>
```

### Right-Aligned Group

The `isRight` prop aligns the button group to the right edge of its container. This is useful for actions that should be visually separated from other content.

```tsx live
<Buttons isRight>
  <Button color="success">Accept</Button>
  <Button color="danger">Reject</Button>
</Buttons>
```

---

## Accessibility

- Grouping buttons in a `` has no negative impact on accessibility.
- Ensure each `Button` has a clear label (text or `aria-label`).
- If grouping radio or toggle buttons, consider `aria-pressed` or `aria-checked` for stateful controls.

:::tip
You can use all Bulma helper props (spacing, color, alignment) with `Buttons` for even more control.
:::

---

## Related Components

- [`Button`](./button.md): The underlying button component used in the group.
- [Helper Props](../helpers/usebulmaclasses.md): All supported Bulma helper props for layout, color, and spacing.

---

## Additional Resources

- [Bulma Button Group Documentation](https://bulma.io/documentation/elements/button/#group)
- [Storybook: Button Stories](https://bestax.io/storybook/?path=/story/elements-button--default)

---

## Code


## Overview

The `Code` component renders a styled `<code>` element with Bulma helper class integration. Use it for inline code snippets, variable names, function names, file paths, or any short technical content that should be displayed in a monospace font.

:::info
For multi-line code blocks, use the `Pre` component instead, optionally with a `Code` component inside it.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                               |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Code content to render inside the element.       |
| ...         | All standard `<code>` and Bulma helper props                                                                                                                                                                                                                                             |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Code

The default usage renders inline code in a monospace font.

```tsx live
<Code>console.log("Hello, World!")</Code>
```

### Variable Name

Reference variable names inline within text.

```tsx live
<Paragraph>
  The <Code>userName</Code> variable stores the current user's name.
</Paragraph>
```

### Function Call

Reference function or method calls.

```tsx live
<Paragraph>
  Use <Code>Array.map()</Code> to transform each element in the array.
</Paragraph>
```

### Command Line

Display command line instructions.

```tsx live
<Paragraph>
  Run <Code>pnpm install</Code> to install the dependencies.
</Paragraph>
```

### Colored Code

Apply text color for syntax highlighting or emphasis.

```tsx live
<Code textColor="primary">import React from "react"</Code>
```

### Code with Background

Add background color and padding for visibility.

```tsx live
<Code bgColor="light" p="1">
  const x = 42
</Code>
```

### All Colors

Display code in all Bulma theme colors.

```tsx live
<Block display="flex" flexDirection="column" gap="2">
  <Code textColor="primary">primary code</Code>
  <Code textColor="link">link code</Code>
  <Code textColor="info">info code</Code>
  <Code textColor="success">success code</Code>
  <Code textColor="warning">warning code</Code>
  <Code textColor="danger">danger code</Code>
</Block>
```

### File Path

Display file or directory paths.

```tsx live
<Paragraph>
  Edit the configuration file at <Code>src/config/settings.ts</Code> to change
  the default values.
</Paragraph>
```

### Keyboard Shortcuts

Display keyboard shortcuts.

```tsx live
<Paragraph>
  Press <Code>Ctrl + C</Code> to copy and <Code>Ctrl + V</Code> to paste.
</Paragraph>
```

---

## Accessibility

- **Code Semantics:** Screen readers may indicate code content differently, helping users understand it's technical content.
- **Monospace Font:** The `<code>` element typically renders in a monospace font, aiding readability of technical content.
- **Context:** Provide context around code snippets so users understand what the code represents.

:::info
Use `Code` for short inline snippets. For multi-line code blocks that need to preserve whitespace and formatting, use the `Pre` component.
:::

---

## Related Components

- [`Pre`](./pre.md): For multi-line preformatted code blocks.
- [`Figure`](./figure.md): For code figures with captions.
- [`Paragraph`](./paragraph.md): For text paragraphs containing code.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [MDN: code element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/code)
- [Storybook: Code Stories](https://bestax.io/storybook/?path=/story/elements-code--default)

---

## Content


## Overview

The `Content` component applies Bulma’s typographic styles to its children, enhancing the appearance of HTML elements like paragraphs, headings, lists, and tables. It supports Bulma size modifiers and helper classes for color, alignment, spacing, and more, making it ideal for rendering rich or markdown-like HTML content.

:::info
The `Content` component is perfect for displaying user-generated content, documentation, or any HTML you want styled consistently.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                                         |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------- |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                                             |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper (e.g., `'danger'` for `has-text-danger`).         |
| `color`     | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`                                                                                                                                                                                                                    | —       | Bulma color modifier for the content.                               |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper (e.g., `'info'` for `has-background-info`). |
| `size`      | `'small' \| 'normal' \| 'medium' \| 'large'`                                                                                                                                                                                                                                             | —       | Size modifier for the content.                                      |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Content to be rendered inside the block.                            |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                              |         | (See [Helper Props](../helpers/usebulmaclasses))                    |

---

## Usage

### Default Content

The simplest use of the `Content` component, rendering a paragraph with default styles.

```tsx live
<Content>
  This is a paragraph inside Content.
</Content>
```

### Primary Text Color

Use the `textColor` prop to apply Bulma's text color helpers. This example uses `textColor="primary"` to make the text color primary.

```tsx live
<Content textColor="primary">Content with Primary Text</Content>
```

### Light Background

The `bgColor` prop applies a background color helper. Here, `bgColor="light"` gives the content a light background.

```tsx live
<Content bgColor="light">Content with Light Background</Content>
```

### Medium Size

The `size` prop allows you to adjust the overall font size and spacing of the content. Here, `size="medium"` increases the text size and padding for better readability.

```tsx live
<Content size="medium">Content with Medium Size</Content>
```

### Spacing and Alignment

You can use Bulma helper props like `m`, `p`, and `textAlign` to control margin, padding, and text alignment. This example centers the text and adds margin and padding for a visually balanced content block.

```tsx live
<Content m="4" p="4" textAlign="centered">
  Content with Margin, Padding, and Centered Text
</Content>
```

### Custom Class

Add your own CSS classes with the `className` prop to further customize the content's appearance or behavior, such as adding custom backgrounds or effects.

```tsx live
<Content className="custom-content-class">Content with Custom Class</Content>
```

### Viewport-Specific Text Color

The `viewport` prop lets you apply color or other helpers at specific breakpoints. Here, `textColor="primary"` is only applied on tablet and larger screens, making the content adapt to different devices.

```tsx live
<Content textColor="primary" viewport="tablet">
  Content with Tablet-specific Primary Text
</Content>
```

### Interactive Content

Combine multiple props such as `textColor`, `bgColor`, `size`, `m`, `p`, and `textAlign` to create visually distinct and interactive content blocks for advanced layouts or callouts.

```tsx live
<Content
  textColor="success"
  bgColor="dark"
  size="large"
  m="3"
  p="3"
  textAlign="right"
>
  Interactive Content
</Content>
```

### Typographic Elements

The `Content` component automatically styles HTML elements like headings, paragraphs, lists, and blockquotes. This example demonstrates how various HTML tags are rendered with Bulma's typographic styles.

```tsx live
<Content textColor="info" p="3">
  Heading 1
  This is a paragraph styled by Bulma’s content class.
  
    Item 1
    Item 2
  
  <blockquote>This is a blockquote styled by Bulma.</blockquote>
</Content>
```

### Rich Content (all HTML tags, various sizes)

This example shows a mix of headings, lists, blockquotes, and tables, with the `size` and `textColor` props applied. Use this for rendering rich, markdown-like content with consistent Bulma styling.

```tsx live
<Content size="small" textColor="primary" p="3">
  Lorem Ipsum Heading
  
    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  
  
    Lorem ipsum
    Consectetur
    Sed do eiusmod
  
  
    First item
    Second item
  
  <blockquote>
    Duis aute irure dolor in reprehenderit in voluptate velit esse cillum.
  </blockquote>
  
    
      
        Header 1
        Header 2
      
    
    
      
        Row 1, Cell 1
        Row 1, Cell 2
      
    
  
</Content>
```

---

## Accessibility

- **Semantic HTML:** Use semantic elements (``, ``, ``, etc.) as children of `Content`.
- **Contrast:** Use appropriate text and background color combinations for readability.
- **Headings:** Keep heading structure meaningful for screen readers.

:::tip
The `Content` component does not add ARIA roles. You are responsible for semantic HTML structure within it.
:::

---

## Related Components

- [`Block`](./block.md): For simple vertical spacing between blocks of content.
- [`Box`](./box.md): For visually distinct, bordered containers.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Content Documentation](https://bulma.io/documentation/elements/content/)
- [MDN: HTML Content Categories](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories)
- [Storybook: Content Stories](https://bestax.io/storybook/?path=/story/elements-content--default)

:::info
Use `Content` for any rich HTML or markdown output to ensure consistent Bulma styling.
:::

---

## Delete


## Overview

The `Delete` component provides a Bulma-styled close/delete button for dismissing modals, notifications, tags, messages, and more. It supports all Bulma size and color helpers, and includes accessibility best practices.

:::info
This component is ideal for adding a visually consistent, accessible close button to any Bulma-styled element.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default   | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------ |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —         | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —         | Text color helper.                               |
| `color`     | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`                                                                                                                                                                                                                    | —         | Bulma color modifier for the button.             |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —         | Background color helper.                         |
| `size`      | `'small' \| 'medium' \| 'large'`                                                                                                                                                                                                                                                         | —         | Size modifier for the delete button.             |
| `onClick`   | `(event: React.MouseEvent<HTMLButtonElement>) => void`                                                                                                                                                                                                                                   | —         | Click handler for the button.                    |
| `ariaLabel` | `string`                                                                                                                                                                                                                                                                                 | `'Close'` | ARIA label for accessibility.                    |
| `disabled`  | `boolean`                                                                                                                                                                                                                                                                                | `false`   | Whether the button is disabled.                  |
| ...         | All standard `<button>` and Bulma helper props                                                                                                                                                                                                                                           |           | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Delete

The default usage of the `Delete` component renders a Bulma-styled close button. Use this for dismissing modals, notifications, tags, or any element that needs a consistent close/delete action.

```tsx live
<Delete />
```

### Small, Medium, Large

The `size` prop allows you to adjust the button size. Use `size="small"`, `size="medium"`, or `size="large"` to match the context of your UI.

```tsx live
<>
  <Delete size="small" />
  <Delete size="medium" />
  <Delete size="large" />
</>
```

### Disabled

The `disabled` prop disables the button, making it non-interactive and visually muted. Use this when the close action should be temporarily unavailable.

```tsx live
<Delete disabled />
```

### With Custom Class

Add your own CSS classes with the `className` prop to further customize the delete button's appearance or behavior.

```tsx live
<Delete className="custom-delete" />
```

### With Text Color

Set the text color using the `textColor` prop. For example, `textColor="primary"` applies Bulma's primary color to the button.

```tsx live
<Delete textColor="primary" />
```

### With Background Color

Apply a background color using the `bgColor` prop. Here, `bgColor="info"` gives the button a colored background.

```tsx live
<Delete bgColor="info" />
```

### With Margin

You can use Bulma spacing helpers like `m` to add margin around the button for better layout control.

```tsx live
<Delete m="2" />
```

### In a Tag

The `Delete` component is often used inside a `Tag` for removable labels. This example shows a small, colored delete button inside a tag.

```tsx live
<Tag color="info" size="medium">
  Example Tag
  <Delete size="small" textColor="danger" ariaLabel="Remove tag" />
</Tag>
```

### In a Notification

Use the `Delete` component inside a `Notification` to provide a dismiss action for alerts or messages.

```tsx live
<Notification color="primary">
  <Delete bgColor="warning" ariaLabel="Close notification" />
  <Paragraph>This is a primary notification with a delete button.</Paragraph>
</Notification>
```

### In a Message Header

The `Delete` component can be placed in a message header for dismissible messages. Combine with spacing and color props for best results.

```tsx live
<Message color="success" title="Success Message">
  This is a success message with a delete button in the header.
</Message>
```

---

## Accessibility

- **ARIA label:** Always set a meaningful `ariaLabel` for screen readers (default is `'Close'`).
- **Keyboard:** The button is focusable and supports keyboard activation.
- **Disabled:** Uses both `disabled` and Bulma’s `is-disabled` for proper styling and accessibility.

:::tip
For custom close actions, use the `onClick` prop.
:::

---

## Related Components

- [`Notification`](../elements/notification.md): For dismissible alerts.
- [`Tag`](../elements/tag.md): For removable tag UI.
- [`Message`](../components/message.md): For dismissible messages.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Delete Documentation](https://bulma.io/documentation/elements/delete/)
- [Storybook: Delete Stories](https://bestax.io/storybook/?path=/story/elements-delete--default)

---

## Divider


## Overview

The `Divider` component renders a styled horizontal rule (``) element with Bulma helper class integration. Use it to visually separate content sections with a clean horizontal line.

:::info
The Divider component is a thin wrapper around the HTML `` element, providing consistent Bulma styling and helper class support.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                               |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Divider

The default usage of the `Divider` component renders a standard horizontal rule.

```tsx live
<>
  <Block>Content above the divider</Block>
  <Divider />
  <Block>Content below the divider</Block>
</>
```

### With Vertical Margin

Use margin helpers to add spacing around the divider.

```tsx live
<>
  <Block>Content above</Block>
  <Divider my="6" />
  <Block>Content below</Block>
</>
```

### Colored Divider

Apply a background color to create a colored divider line.

```tsx live
<>
  <Block>Content above</Block>
  <Divider bgColor="primary" />
  <Block>Content below</Block>
</>
```

### All Colors

Display dividers in various Bulma theme colors.

```tsx live
<>
  <Block>Default</Block>
  <Divider />
  <Block>Primary</Block>
  <Divider bgColor="primary" />
  <Block>Info</Block>
  <Divider bgColor="info" />
  <Block>Success</Block>
  <Divider bgColor="success" />
  <Block>Warning</Block>
  <Divider bgColor="warning" />
  <Block>Danger</Block>
  <Divider bgColor="danger" />
  <Block>End</Block>
</>
```

### Separating Content Sections

Use dividers to create visual separation between major content sections.

```tsx live
<>
  <Title size="4">Section One</Title>
  <Paragraph>This is the first section of content.</Paragraph>
  <Divider my="5" />
  <Title size="4">Section Two</Title>
  <Paragraph>This is the second section of content.</Paragraph>
  <Divider my="5" />
  <Title size="4">Section Three</Title>
  <Paragraph>This is the third section of content.</Paragraph>
</>
```

---

## Accessibility

- **Visual Separation:** The `` element provides visual separation and has implicit semantic meaning as a thematic break.
- **Screen Readers:** Screen readers typically announce `` elements, so use them meaningfully to separate distinct content sections.
- **Decorative Use:** If the divider is purely decorative, consider using CSS borders instead.

:::info
Use dividers for thematic breaks between content sections, not just for visual spacing (use margin helpers for spacing alone).
:::

---

## Related Components

- [`Block`](./block.md): For content containers with vertical spacing.
- [`Box`](./box.md): For bordered content containers.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [MDN: hr element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr)
- [Storybook: Divider Stories](https://bestax.io/storybook/?path=/story/elements-divider--default)

---

## Emphasis


## Overview

The `Emphasis` component renders a styled `` element with Bulma helper class integration. Use it for text that has stress emphasis, which subtly changes the meaning of a sentence. The `` element carries semantic meaning for screen readers.

:::info
For visual-only italic styling without semantic meaning, use CSS `font-style: italic` instead.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                               |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Content to render inside the em element.         |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                               |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Emphasis

The default usage renders emphasized (italic) text with semantic meaning.

```tsx live
<Emphasis>Emphasized text</Emphasis>
```

### Colored Emphasis

Apply text color for additional visual distinction.

```tsx live
<Emphasis textColor="primary">Primary emphasized text</Emphasis>
```

### Info Emphasis

Use info color for notes or supplementary information.

```tsx live
<Emphasis textColor="info">Note this important detail</Emphasis>
```

### Emphasis with Background

Add background color and padding for a highlight effect.

```tsx live
<Emphasis bgColor="light" textColor="dark" p="1">
  Highlighted emphasis
</Emphasis>
```

### Inline with Text

Emphasis works naturally inline within paragraphs.

```tsx live
<Paragraph>
  This is a paragraph with <Emphasis>emphasized text</Emphasis> in the middle.
  You should <Emphasis textColor="info">really</Emphasis> pay attention to this.
</Paragraph>
```

### All Colors

Display emphasized text in all Bulma theme colors.

```tsx live
<Block display="flex" flexDirection="column" gap="2">
  <Emphasis textColor="primary">Primary emphasis</Emphasis>
  <Emphasis textColor="link">Link emphasis</Emphasis>
  <Emphasis textColor="info">Info emphasis</Emphasis>
  <Emphasis textColor="success">Success emphasis</Emphasis>
  <Emphasis textColor="warning">Warning emphasis</Emphasis>
  <Emphasis textColor="danger">Danger emphasis</Emphasis>
</Block>
```

### Quotation Style

Use emphasis for quoted phrases or sayings.

```tsx live
<Paragraph>
  As the saying goes, <Emphasis>actions speak louder than words</Emphasis>.
</Paragraph>
```

### Technical Terms

Use emphasis when introducing technical terms.

```tsx live
<Paragraph>
  The <Emphasis>idempotent</Emphasis> operation can be applied multiple times
  without changing the result beyond the initial application.
</Paragraph>
```

---

## Accessibility

- **Stress Emphasis:** Screen readers may announce `` content with a change in tone or stress.
- **Appropriate Use:** Use `` for content that requires stress emphasis, not just for visual styling.
- **Nested Emphasis:** Multiple levels of `` indicate greater degrees of emphasis.

:::info
The `` element indicates stress emphasis that subtly changes the meaning of a sentence. Compare "I _love_ coding" vs "I love _coding_".
:::

---

## Related Components

- [`Strong`](./strong.md): For semantically important bold text.
- [`Span`](./span.md): For styled inline text without semantic meaning.
- [`Paragraph`](./paragraph.md): For text paragraphs.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [MDN: em element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em)
- [Storybook: Emphasis Stories](https://bestax.io/storybook/?path=/story/elements-emphasis--default)

---

## Figure


## Overview

The `Figure` component renders a styled `<figure>` element with Bulma helper class integration. Use it to group self-contained content like images, illustrations, diagrams, or code snippets with an optional caption via `Figure.Caption`.

:::info
The Figure component is a thin wrapper around the HTML `<figure>` element with a `Figure.Caption` subcomponent for `<figcaption>`.
:::

---

## Import

```tsx

```

---

## Props

### Figure Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                               |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Content to render inside the figure.             |
| ...         | All standard `<figure>` and Bulma helper props                                                                                                                                                                                                                                           |         | (See [Helper Props](../helpers/usebulmaclasses)) |

### Figure.Caption Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                               |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Caption text to render.                          |
| ...         | All standard `<figcaption>` and Bulma helper props                                                                                                                                                                                                                                       |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Figure

The default usage of the `Figure` component with an image.

```tsx live
<Figure>
  <Image src="/img/bestax-solar-system-3d.png" alt="Placeholder" />
</Figure>
```

### Figure with Caption

Add a caption using `Figure.Caption`.

```tsx live
<Figure>
  <Image src="/img/bestax-solar-system-3d.png" alt="Placeholder" />
  <Figure.Caption>This is a caption for the image</Figure.Caption>
</Figure>
```

### Styled Caption

Apply color and typography helpers to the caption.

```tsx live
<Figure>
  <Image src="/img/bestax-solar-system-3d.png" alt="Placeholder" />
  <Figure.Caption textColor="grey" textSize="7" mt="2">
    Grey caption with smaller text
  </Figure.Caption>
</Figure>
```

### Figure with Background

Add a background and padding to create a framed effect.

```tsx live
<Figure bgColor="light" textColor="dark" p="4">
  <Image src="/img/bestax-solar-system-3d.png" alt="Placeholder" />
  <Figure.Caption mt="2">Figure with background and padding</Figure.Caption>
</Figure>
```

### Centered Caption

Center the caption and content using text alignment.

```tsx live
<Figure textAlign="centered">
  <Image src="/img/bestax-solar-system-3d.png" alt="Placeholder" />
  <Figure.Caption textSize="7" mt="2">
    Centered caption
  </Figure.Caption>
</Figure>
```

### Code Figure

Use Figure to wrap code blocks with captions.

```tsx live
<Figure bgColor="dark" p="4">
  <Pre textColor="white" m="0">
    <Code>{`function hello() {
  console.log("Hello, World!");
}`}</Code>
  </Pre>
  <Figure.Caption textColor="grey-light" mt="2">
    Example code snippet
  </Figure.Caption>
</Figure>
```

---

## Accessibility

- **Image Alt Text:** Always provide meaningful alt text for images within figures.
- **Figure Semantics:** The `<figure>` element groups content that is referenced from the main flow but could be moved without affecting the document's meaning.
- **Caption Association:** Screen readers associate `<figcaption>` content with the figure automatically.

:::info
The `<figure>` element is ideal for images, illustrations, diagrams, code listings, or anything that is referenced as a unit from the main content.
:::

---

## Related Components

- [`Image`](./image.md): For Bulma-styled images.
- [`Pre`](./pre.md): For preformatted code blocks.
- [`Code`](./code.md): For inline code.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [MDN: figure element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure)
- [MDN: figcaption element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption)
- [Storybook: Figure Stories](https://bestax.io/storybook/?path=/story/elements-figure--default)

---

## Icon


## Overview

The `Icon` component is a Bulma-styled wrapper for displaying icons from various libraries (Font Awesome, Material Design Icons, Ionicons, Google Material Icons, Material Symbols, etc.). It handles Bulma sizing, colors, helper props, and accessibility. You can use it standalone or inside other components (like `Button`, `Tag`, or `IconText`).

:::info
Font Awesome is the default icon library, but you can use Material Design Icons, Ionicons, Google Material Icons, or Material Symbols by changing the `library` prop. For setup instructions, see [Alternative Icons](/docs/guides/getting-started/alternative-icons).
:::

---

## Import

```tsx

```

---

## Props

| Prop                 | Type                                                                                                                                                                                                                                                                                     | Default  | Description                                                           |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------------------------------------------- |
| `className`          | `string`                                                                                                                                                                                                                                                                                 | —        | Additional CSS classes.                                               |
| `textColor`          | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —        | Text color helper.                                                    |
| `color`              | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`                                                                                                                                                                                                                    | —        | Bulma color modifier for the icon.                                    |
| `bgColor`            | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —        | Background color helper.                                              |
| `name`               | `string`                                                                                                                                                                                                                                                                                 |          | The icon name (without library prefix, e.g. `'star'`).                |
| `library`            | `'fa' \| 'mdi' \| 'ion' \| 'material-icons' \| 'material-symbols'`                                                                                                                                                                                                                       | `'fa'`   | The icon library to use.                                              |
| `variant`            | `string`                                                                                                                                                                                                                                                                                 | —        | Icon style variant (e.g. `'solid'`, `'outlined'`, `'rounded'`).       |
| `features`           | `string \| string[]`                                                                                                                                                                                                                                                                     | —        | Additional modifiers (e.g. `'fa-lg'`, `'fa-spin'`, `'is-size-1'`).    |
| `libraryFeatures`    | `string \| string[]`                                                                                                                                                                                                                                                                     | —        | **DEPRECATED:** Use `variant` and `features` instead.                 |
| `size`               | `'small' \| 'medium' \| 'large'`                                                                                                                                                                                                                                                         | —        | Size modifier for the icon container.                                 |
| `ariaLabel`          | `string`                                                                                                                                                                                                                                                                                 | `'icon'` | ARIA label for accessibility.                                         |
| `style`              | `object`                                                                                                                                                                                                                                                                                 | —        | Inline style object.                                                  |
| `containerClassName` | `string`                                                                                                                                                                                                                                                                                 | —        | Override the default `'icon'` container class (e.g., `'panel-icon'`). |
| ...                  | All standard `` and Bulma helper props                                                                                                                                                                                                                                             |          | (See [Helper Props](../helpers/usebulmaclasses))                      |

---

## Usage

### Default Icon (Font Awesome)

The simplest use of the `Icon` component, displaying a Font Awesome star icon. The `ariaLabel` prop provides an accessible name for the icon.

```tsx live
<Icon name="star" ariaLabel="Star icon" />
```

### Font Awesome Large

You can use the `variant` and `features` props for Font Awesome-specific styling. In this example, `variant="solid"` specifies the icon style and `features="fa-2x"` increases the icon size to 2x its normal size.

```tsx live
<Icon
  name="star"
  variant="solid"
  features="fa-2x"
  ariaLabel="Star icon large"
/>
```

### Spinning Icon

The `features` prop can be used to add Font Awesome modifiers like `fa-spin` for animated icons. This example shows a spinning loading icon with increased size.

```tsx live
<Icon
  name="spinner"
  variant="solid"
  features={['fa-spin', 'fa-2x']}
  ariaLabel="Loading spinner"
/>
```

### Bordered

You can add a border to the icon using Font Awesome's `fa-border` class via the `features` prop. This is useful for icons that need to stand out or be visually separated.

```tsx live
<Icon
  name="star"
  size="large"
  variant="solid"
  features={['fa-border', 'fa-2x']}
  ariaLabel="Star bordered"
/>
```

### With Text Color

Set the icon color using the `textColor` prop. For example, `textColor="primary"` applies Bulma's primary color to the icon.

```tsx live
<Icon
  name="star"
  textColor="primary"
  ariaLabel="Star icon with primary text color"
/>
```

### With Margin

You can use Bulma spacing helpers like `m` to add margin around the icon for better layout control.

```tsx live
<Icon name="star" m="2" ariaLabel="Star icon with margin" />
```

### With Container Size

The `size` prop adjusts the size of the icon container. Use `size="large"` for a bigger icon wrapper, which is useful for emphasis or visual hierarchy.

```tsx live
<Icon name="star" size="large" ariaLabel="Star icon large container" />
```

### Google Material Icons

Use Google's official Material Icons with different styles available through `variant`.

```tsx live
<Block display="flex" gap="4" alignItems="center">
  <Icon library="material-icons" name="favorite" ariaLabel="Filled heart" />
  <Icon
    library="material-icons"
    name="favorite"
    variant="outlined"
    ariaLabel="Outlined heart"
  />
  <Icon
    library="material-icons"
    name="favorite"
    variant="round"
    ariaLabel="Round heart"
  />
</Block>
```

### Material Symbols

Google's newest icon system with modern design and comprehensive coverage.

```tsx live
<Block display="flex" gap="4" alignItems="center">
  <Icon
    library="material-symbols"
    name="settings"
    ariaLabel="Settings outlined"
  />
  <Icon
    library="material-symbols"
    name="settings"
    variant="rounded"
    ariaLabel="Settings rounded"
  />
  <Icon
    library="material-symbols"
    name="settings"
    variant="sharp"
    ariaLabel="Settings sharp"
  />
</Block>
```

### Material Design Icons

Comprehensive Material Design icon library with thousands of icons.

```tsx live
<Icon library="mdi" name="home" ariaLabel="Material Design home icon" />
```

### Ionicons

Modern icon library with web components support, perfect for mobile-first applications.

```tsx live
<Icon library="ion" name="settings" ariaLabel="Ionicons settings icon" />
```

---

## Accessibility

- **ARIA label:** Always set a meaningful `ariaLabel` for screen readers (default `'icon'`).
- **Keyboard:** Icon is decorative by default. If interactive, use with `Button` or `a` and add ARIA as needed.
- **Color and size:** Use `textColor`, `bgColor`, and `size` for accessible, themeable icons.

:::note
For purely decorative icons, you can use `aria-hidden="true"` via the `...rest` props.
:::

---

## Related Components

- [`IconText`](./icontext.md): For icons with adjacent text.
- [`Button`](./button.md): For buttons with icons.
- [`Card`](../components/card.md): For cards with header icons and content.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Icon Documentation](https://bulma.io/documentation/elements/icon/)
- [Font Awesome Docs](https://fontawesome.com/docs/web/use-with/react/)
- [Storybook: Icon Stories](https://bestax.io/storybook/?path=/story/elements-icon--default)

---

## IconText


## Overview

The `IconText` component provides a Bulma-styled horizontal arrangement of one or more `Icon` components and optional text. Use it for icon-and-label patterns, ratings, button content, or any visual+text UI. Supports all Bulma helper props for spacing, color, and layout.

:::tip
Use `IconText` to keep icons and text vertically aligned and spaced, as recommended by Bulma.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                               |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------- |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                                   |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                                        |
| `color`     | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`                                                                                                                                                                                                                    | —       | Bulma color modifier for the icon text group.             |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                                  |
| `iconProps` | `IconProps`                                                                                                                                                                                                                                                                              | —       | Props for a single Icon component (for single icon mode). |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Text for a single icon (for single icon mode).            |
| `items`     | `{ iconProps: IconProps, text?: string }[]`                                                                                                                                                                                                                                              | —       | Array of icon/text pairs (for multiple icons mode).       |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                             |         | (See [Helper Props](../helpers/usebulmaclasses))          |

---

## Usage

### Single Icon + Text

A basic usage of the `IconText` component with a single icon and text. The `iconProps` object receives the icon's name and an `ariaLabel` for accessibility.

```tsx live
<IconText iconProps={{ library: 'fa', name: 'star', ariaLabel: 'Star icon' }}>
  Star
</IconText>
```

### With Text Color

You can customize the text color using Bulma's color helpers. This example shows a primary colored text.

```tsx live
<IconText
  iconProps={{ library: 'fa', name: 'star', ariaLabel: 'Star icon' }}
  textColor="primary"
>
  Star
</IconText>
```

### With Margin

You can use Bulma spacing helpers like `m` to add margin around the `IconText` component for better layout control.

```tsx live
<IconText
  iconProps={{ library: 'fa', name: 'star', ariaLabel: 'Star icon' }}
  m="2"
>
  Star
</IconText>
```

### In a Button

Use `IconText` inside a button to combine an icon and label, ensuring proper alignment and spacing.

```tsx live
<Button color="primary">
  <IconText
    iconProps={{
      library: 'fa',
      name: 'check',
      ariaLabel: 'Check icon',
    }}
  >
    Click Me
  </IconText>
</Button>
```

### In a Notification

Place `IconText` inside a notification to visually pair an icon with a message, using color and margin helpers for emphasis.

```tsx live
<Notification color="info">
  <IconText
    iconProps={{
      library: 'fa',
      name: 'info-circle',
      ariaLabel: 'Info icon',
      textColor: 'dark',
    }}
    m="1"
  >
    Info Notification
  </IconText>
</Notification>
```

### In a Tag

Use `IconText` inside a tag for labeled icons, such as status indicators or badges.

```tsx live
<Tag color="success" size="medium">
  <IconText
    iconProps={{
      library: 'fa',
      name: 'check',
      ariaLabel: 'Check icon',
    }}
  >
    Success
  </IconText>
</Tag>
```

### Multiple Icons and Text

The `items` prop allows you to render a sequence of icons and optional text, perfect for visualizing progress, routes, or multi-step processes.

```tsx live
<IconText
  items={[
    {
      iconProps: { library: 'fa', name: 'train', ariaLabel: 'Train icon' },
      text: 'Paris',
    },
    {
      iconProps: {
        library: 'fa',
        name: 'arrow-right',
        ariaLabel: 'Arrow right icon',
      },
      text: 'Budapest',
    },
    {
      iconProps: {
        library: 'fa',
        name: 'arrow-right',
        ariaLabel: 'Arrow right icon',
      },
      text: 'Bucharest',
    },
    {
      iconProps: {
        library: 'fa',
        name: 'arrow-right',
        ariaLabel: 'Arrow right icon',
      },
      text: 'Istanbul',
    },
    {
      iconProps: {
        library: 'fa',
        name: 'flag-checkered',
        ariaLabel: 'Finish icon',
      },
    },
  ]}
  mx="1"
/>
```

### Star Rating Example

This example uses the `items` prop to display a star rating with icons and text, demonstrating how to build composite icon+text UIs.

:::tip Use the Rate Component for Star Ratings
This example demonstrates IconText with multiple icon items. For actual star rating functionality (hover, click, keyboard, precision, etc.), use the dedicated [`Rate`](/docs/api/form/rate) component:

```tsx live
<Rate defaultValue={3.5} color="warning" precision={0.5} showScore />
```

:::

```tsx live
<IconText
  items={[
    {
      iconProps: {
        library: 'fa',
        name: 'star',
        ariaLabel: 'Star icon',
      },
    },
    {
      iconProps: {
        library: 'fa',
        name: 'star',
        ariaLabel: 'Star icon',
      },
    },
    {
      iconProps: {
        library: 'fa',
        name: 'star',
        ariaLabel: 'Star icon',
      },
    },
    {
      iconProps: {
        library: 'fa',
        name: 'star-half-alt',
        ariaLabel: 'Half star icon',
      },
    },
    {
      iconProps: {
        library: 'fa',
        name: 'star',
        variant: 'regular',
        ariaLabel: 'Empty star icon',
      },
      text: '3.5/5',
    },
  ]}
  textColor="warning"
  mx="1"
/>
```

### With Flex

The `display` prop can be used to apply Bulma's flexbox helpers, allowing for flexible alignment and layout of icon and text content.

```tsx live
<IconText
  iconProps={{
    library: 'fa',
    name: 'info-circle',
    ariaLabel: 'Info icon',
    textColor: 'info',
  }}
  display="flex"
>
  Information
</IconText>
```

---

## Accessibility

- **ARIA labels:** Always set an `ariaLabel` for icons for screen readers.
- **Order:** The icon is visually before the text by default.
- **Keyboard:** If used in a button or link, keyboard accessibility is handled by the parent.

:::info
For star ratings or icon lists, use `items` with `iconProps` and optional `text`.
:::

---

## Related Components

- [`Icon`](./icon.md): For standalone icons.
- [`Button`](./button.md): For icon-button combos.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma IconText Documentation](https://bulma.io/documentation/elements/icon/#icon-text)
- [Storybook: IconText Stories](https://bestax.io/storybook/?path=/story/elements-icontext--default)

---

## Image


## Overview

The `Image` component wraps images, iframes, or custom content in a Bulma-styled container, supporting fixed sizes, aspect ratios, rounded corners, retina images, and all Bulma helper props for color and spacing.

:::info
Use `Image` for consistent responsive image containers, or to embed arbitrary media (like iframes) with Bulma styling.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                                                                     |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------------------- |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                                                                         |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper for the container.                                                            |
| `color`     | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`                                                                                                                                                                                                                    | —       | Bulma color modifier for the image container.                                                   |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper for the container.                                                      |
| `size`      | Bulma size string (e.g., `'128x128'`, `'16by9'`, `'square'`)                                                                                                                                                                                                                             | —       | Fixed size or aspect ratio modifier for the image container.                                    |
| `isRounded` | `boolean`                                                                                                                                                                                                                                                                                | —       | Renders the image with rounded corners.                                                         |
| `isRetina`  | `boolean`                                                                                                                                                                                                                                                                                | —       | Uses retina (2x) image source.                                                                  |
| `src`       | `string`                                                                                                                                                                                                                                                                                 | —       | Image source URL.                                                                               |
| `alt`       | `string`                                                                                                                                                                                                                                                                                 | —       | Alternate text for the image.                                                                   |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Arbitrary content (e.g., iframe, custom HTML) inside the image container.                       |
| `as`        | `'figure' \| 'div' \| 'p'`                                                                                                                                                                                                                                                               | —       | Container element tag. Defaults to `'figure'` when using aspect-ratio sizes, `'div'` otherwise. |
| ...         | All standard `<figure>`/`` and Bulma helper props                                                                                                                                                                                                                                   |         | (See [Helper Props](../helpers/usebulmaclasses))                                                |

---

## Usage

### Default Image

The simplest usage of the `Image` component, requiring only the `src` and `alt` props. The `size` prop controls the dimensions.

```tsx live
<Image
  src="/img/bestax-solar-system-3d.png"
  alt="Sample image"
  size="128x128"
/>
```

### Rounded Image

The `isRounded` prop adds rounded corners to the image, useful for profile pictures or any image where a softer look is desired.

```tsx live
<Image
  src="/img/bestax-solar-system-3d.png"
  alt="Rounded image"
  size="128x128"
  isRounded
/>
```

### Retina Image

The `isRetina` prop enables support for high-resolution (2x) images, ensuring crisp visuals on retina displays. Use this for logos or images that need to look sharp on all devices.

```tsx live
<Image
  src="/img/bestax-solar-system-3d.png"
  alt="Retina image"
  size="128x128"
  isRetina
/>
```

### Aspect Ratio 16:9

Set the `size` prop to `16by9` to create a responsive image container with a 16:9 aspect ratio. This is ideal for video thumbnails or wide images.

```tsx live
<Image
  src="/img/bestax-solar-system-3d.png"
  alt="16:9 aspect ratio image"
  size="16by9"
/>
```

### Aspect Ratio 4:3

Set the `size` prop to `4by3` for a classic photo or video aspect ratio. This helps maintain consistent layouts for media content.

```tsx live
<Image
  src="/img/bestax-solar-system-3d.png"
  alt="4:3 aspect ratio image"
  size="4by3"
/>
```

### With Margin

You can use Bulma spacing helpers like `m` to add margin around the image for better layout control.

```tsx live
<Image
  src="/img/bestax-solar-system-3d.png"
  alt="Image with margin"
  size="128x128"
  m="4"
/>
```

### With Iframe

The `Image` component can wrap arbitrary children, such as iframes, to provide responsive aspect ratios and Bulma styling for embedded media.

```tsx live
<Image size="16by9">
  <iframe
    className="has-ratio"
    width="640"
    height="360"
    src="https://www.youtube.com/embed/YE7VzlLtp-4"
    frameBorder="0"
    allowFullScreen
    title="Sample YouTube Video"
  />
</Image>
```

### With Custom Child

You can also wrap custom content inside the `Image` component, such as a styled div or any React node, to maintain aspect ratio and Bulma styling.

```tsx live
<Image size="4by3">
  <Block
    display="flex"
    alignItems="center"
    justifyContent="center"
    bgColor="grey-light"
    textColor="dark"
    textAlign="centered"
    className="has-ratio"
    style={{ height: '100%' }}
  >
    <Paragraph>Custom Content</Paragraph>
  </Block>
</Image>
```

### With Text Color and Background

Combine the `textColor` and `bgColor` props to style the image container for branding or emphasis.

```tsx live
<Image
  src="/img/bestax-solar-system-3d.png"
  alt="Image with text and background color"
  size="128x128"
  textColor="primary"
  bgColor="light"
/>
```

---

## Accessibility

- **Alt Text:** Always provide a descriptive `alt` attribute for images.
- **Aspect Ratios:** Maintains the correct aspect ratio for images, iframes, or any child.
- **Custom Content:** When embedding iframes or custom children, ensure accessibility via proper ARIA labeling or content.

:::warning
Do not use `Image` for decorative images without `alt=""`, unless purely presentational.
:::

---

## Related Components

- [`Box`](./box.md): For bordered, padded containers.
- [`Content`](./content.md): For typographically styled rich content.
- [`Card`](../components/card.md): For cards with responsive images and proper aspect ratios.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Image Documentation](https://bulma.io/documentation/elements/image/)
- [Storybook: Image Stories](https://bestax.io/storybook/?path=/story/elements-image--default)

---

## Link


## Overview

The `Link` component renders a styled anchor (``) element with Bulma helper class integration. Use it for navigation links, external links, or any clickable text that follows Bulma's styling conventions. It supports all Bulma helper props for color, spacing, typography, and more.

:::info
The Link component is a thin wrapper around the HTML `` element, providing consistent Bulma styling and helper class support.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                       |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------- |
| `href`      | `string`                                                                                                                                                                                                                                                                                 | —       | The URL the link points to.                       |
| `target`    | `'_self'` \| `'_blank'` \| `'_parent'` \| `'_top'`                                                                                                                                                                                                                                       | —       | Where to open the linked document.                |
| `rel`       | `string`                                                                                                                                                                                                                                                                                 | —       | Relationship between current and linked document. |
| `isActive`  | `boolean`                                                                                                                                                                                                                                                                                | —       | Whether the link appears active.                  |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                           |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                                |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                          |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Content to render inside the link.                |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                                |         | (See [Helper Props](../helpers/usebulmaclasses))  |

---

## Usage

### Default Link

The default usage of the `Link` component renders a standard anchor element with Bulma styling support.

```tsx live
<Link href="#">Default Link</Link>
```

### Primary Color Link

Set the text color using the `textColor` prop to emphasize the link with Bulma's primary color.

```tsx live
<Link href="#" textColor="primary">
  Primary Link
</Link>
```

### Danger Color Link

Use `textColor="danger"` for links that indicate destructive or warning actions.

```tsx live
<Link href="#" textColor="danger">
  Danger Link
</Link>
```

### Active Link

Apply the `isActive` prop to style the link as currently active, useful for navigation menus.

```tsx live
<Link href="#" isActive>
  Active Link
</Link>
```

### External Link

For external links, set `target="_blank"` and use `rel="noopener noreferrer"` for security.

```tsx live
<Link href="https://bulma.io" target="_blank" rel="noopener noreferrer">
  Open Bulma Docs
</Link>
```

### Link That Looks Like a Button

:::tip Use Button with `as="a"` for Button-Styled Links
If you need a link that looks like a button, use the [`Button`](./button.md) component with `as="a"` and a valid `href`. This ensures proper semantics — the element is still a navigational link, but styled as a button.
:::

:::warning Don't Use Button-Styled Links for Actions
A `<Button as="a">` should still navigate to a URL. If the element triggers an action (no `href`), use a regular [`Button`](./button.md) or [`LinkButton`](./linkbutton.md) instead. Per [Section 508](https://www.section508.gov/) and [eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y), anchor elements must have a valid destination — not just an `onClick` handler.
:::

```tsx live
<Button as="a" href="#" color="primary">
  Button Link
</Button>
```

### Large Text Link

Use the `textSize` prop to increase the link's font size.

```tsx live
<Link href="#" textSize="3">
  Large Link
</Link>
```

### Bold Link

Apply bold text weight using the `textWeight` prop.

```tsx live
<Link href="#" textWeight="bold">
  Bold Link
</Link>
```

### All Colors

Display links in all Bulma theme colors.

```tsx live
<Block display="flex" flexDirection="column" gap="2">
  <Link href="#" textColor="primary">
    Primary Link
  </Link>
  <Link href="#" textColor="link">
    Link Color Link
  </Link>
  <Link href="#" textColor="info">
    Info Link
  </Link>
  <Link href="#" textColor="success">
    Success Link
  </Link>
  <Link href="#" textColor="warning">
    Warning Link
  </Link>
  <Link href="#" textColor="danger">
    Danger Link
  </Link>
</Block>
```

### Inline Link

Links work seamlessly inline within text content.

```tsx live
<Paragraph>
  This is a paragraph with an <Link href="#">inline link</Link> in the middle of
  the text.
</Paragraph>
```

---

## Accessibility

- **Descriptive Text:** Use meaningful link text that describes the destination, not generic text like "click here".
- **External Links:** When opening links in new tabs, consider informing users (e.g., with an icon or text like "opens in new tab").
- **Focus States:** Links inherit browser focus styles. Customize with CSS if needed.
- **Keyboard Navigation:** Links are naturally keyboard accessible via Tab and Enter keys.

:::info
For navigation menus, consider using the `isActive` prop to indicate the current page.
:::

:::warning Links Are for Navigation, Buttons Are for Actions
Per [Section 508](https://www.section508.gov/) and [eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y) best practices, links (``) should navigate to a URL — not trigger an action via `onClick` alone. If your element performs an action (opening a modal, submitting data, toggling state, etc.) without navigating, use a [`Button`](./button.md) or [`LinkButton`](./linkbutton.md) instead. A `<Link href="#" onClick={handleClick}>` is an anti-pattern that confuses screen readers and fails accessibility audits.
:::

---

## Related Components

- [`Button`](./button.md): For button-style clickable elements.
- [`Paragraph`](./paragraph.md): For text paragraphs that may contain links.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Content Documentation](https://bulma.io/documentation/elements/content/)
- [Storybook: Link Stories](https://bestax.io/storybook/?path=/story/elements-link--default)

---

## LinkButton


## Overview

The `LinkButton` component renders a `<button>` that visually looks like text or a link. It provides an accessible replacement for `` anti-patterns by wrapping the [`Button`](./button.md) component with `is-text` or `is-ghost` styling and CSS overrides.

**Two variants:**

- **`text`** — like Bulma's `is-text` button but without the underline. Hover shows a background highlight.
- **`ghost`** — like Bulma's `is-ghost` button but without the link color. Hover shows an underline.

Both variants support an optional `color` prop to set the text color.

:::tip
Use `LinkButton` instead of `` or unstyled click handlers to get proper keyboard navigation, focus handling, and screen reader support for free.
:::

---

## Import

```tsx

```

---

## Props

| Prop          | Type                                                                                                             | Default    | Description                                                             |
| ------------- | ---------------------------------------------------------------------------------------------------------------- | ---------- | ----------------------------------------------------------------------- |
| `variant`     | `'text' \| 'ghost' \| 'underline'`                                                                               | `'text'`   | Display mode. `text` has no underline; `ghost` uses default text color. |
| `color`       | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'white' \| 'light' \| 'dark' \| 'black'` | —          | Text color override for the button.                                     |
| `size`        | `'small' \| 'normal' \| 'medium' \| 'large'`                                                                     | —          | Size of the button.                                                     |
| `isRounded`   | `boolean`                                                                                                        | —          | Makes the button rounded.                                               |
| `isLoading`   | `boolean`                                                                                                        | —          | Displays a loading spinner.                                             |
| `isStatic`    | `boolean`                                                                                                        | —          | Makes the button non-interactive.                                       |
| `isFullWidth` | `boolean`                                                                                                        | —          | Makes the button full-width.                                            |
| `isFocused`   | `boolean`                                                                                                        | —          | Applies focused styling (visual only).                                  |
| `isActive`    | `boolean`                                                                                                        | —          | Applies active styling (visual only).                                   |
| `isHovered`   | `boolean`                                                                                                        | —          | Applies hovered styling (visual only).                                  |
| `isDisabled`  | `boolean`                                                                                                        | —          | Applies disabled styling.                                               |
| `as`          | `'button' \| 'a'`                                                                                                | `'button'` | Render as a `<button>` or ``.                                        |
| `href`        | `string`                                                                                                         | —          | Href value (if rendering as ``).                                     |
| `onClick`     | `function`                                                                                                       | —          | Click event handler.                                                    |
| `className`   | `string`                                                                                                         | —          | Custom class name.                                                      |
| `children`    | `React.ReactNode`                                                                                                | —          | Button content.                                                         |
| ...           | All standard `<button>` and Bulma helper props                                                                   | —          | See [Helper Props](../helpers/usebulmaclasses.md)                       |

:::note
The `isOutlined`, `isInverted`, and `isLight` props from Button are not available on LinkButton — they don't apply to link-like buttons.
:::

---

## Usage

### Default (Text Variant)

The default variant renders a minimal text button without underline. On hover it shows a background highlight.

```tsx live
<LinkButton>Click me</LinkButton>
```

### Ghost Variant

The ghost variant renders a link-like button with default text color (not link color). On hover it shows an underline.

```tsx live
<LinkButton variant="ghost">Ghost LinkButton</LinkButton>
```

### Text Variant with Color

Add a `color` prop to set the text color. The hover behavior remains the same.

```tsx live
<LinkButton color="primary">Primary Text</LinkButton>
```

### Ghost Variant with Color

Colors work with the ghost variant too.

```tsx live
<LinkButton variant="ghost" color="danger">
  Danger Ghost
</LinkButton>
```

### All Colors

```tsx live
<Buttons>
  {['primary', 'link', 'info', 'success', 'warning', 'danger'].map(color => (
    <LinkButton key={color} color={color}>
      {color.charAt(0).toUpperCase() + color.slice(1)}
    </LinkButton>
  ))}
</Buttons>
```

### Disabled

```tsx live
<LinkButton isDisabled disabled>
  Disabled LinkButton
</LinkButton>
```

### All Sizes

```tsx live
<Buttons>
  {['small', 'normal', 'medium', 'large'].map(size => (
    <LinkButton key={size} size={size}>
      {size.charAt(0).toUpperCase() + size.slice(1)}
    </LinkButton>
  ))}
</Buttons>
```

---

## Visual Behavior

|                   | Default text color   | Hover                                 |
| ----------------- | -------------------- | ------------------------------------- |
| **text variant**  | `var(--bulma-text)`  | Background highlight, no underline    |
| **ghost variant** | `var(--bulma-text)`  | Underline appears                     |
| **+ color**       | Uses specified color | Same hover behavior, color maintained |

---

## Accessibility

- **Semantic HTML:** Renders a native `<button>` element, providing correct keyboard navigation, focus management, and screen reader announcements.
- **States:** The `isDisabled` and `disabled` props ensure correct `aria-disabled` and `disabled` attributes.
- **Keyboard:** Fully keyboard accessible with Enter and Space activation.
- **Replaces anti-patterns:** Use this instead of `` or `` for interactive elements that should not navigate.

:::note
If your LinkButton has only an icon, use `aria-label` to provide accessible text.
:::

---

## Related Components

- [`Button`](./button.md): Full-featured button with all Bulma styles.
- [`Buttons`](./buttons.md): Group multiple buttons together.
- [Helper Props](../helpers/usebulmaclasses.md): List of all supported Bulma helper props.

---

## Additional Resources

- [Bulma Button Documentation](https://bulma.io/documentation/elements/button/)
- [React Button Accessibility](https://www.w3.org/WAI/ARIA/apg/patterns/button/)
- [Storybook: LinkButton Stories](https://bestax.io/storybook/?path=/story/elements-linkbutton--default)

---

## ListItem


## Overview

The `ListItem` component renders a styled list item (``) element with Bulma helper class integration. Use it inside `UnorderedList` or `OrderedList` components to create list items with consistent styling.

:::info
The ListItem component is a thin wrapper around the HTML `` element, providing consistent Bulma styling and helper class support.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `value`     | `number`                                                                                                                                                                                                                                                                                 | —       | Custom value for ordered list items.             |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                               |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Content to render inside the list item.          |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                               |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

:::info Wrap Lists in Content for Traditional Styling
Without a [`Content`](./content.md) wrapper, Bulma renders lists without the traditional margin, padding, and list-style markers (bullets, numbers). Wrap your lists in `<Content>` to get the expected typographic list appearance.
:::

### Default List Item

The default usage of the `ListItem` component inside a list.

```tsx live
<Content>
  <UnorderedList>
    <ListItem>Default List Item</ListItem>
    <ListItem>Another item</ListItem>
  </UnorderedList>
</Content>
```

### Colored List Item

Apply text color to individual list items.

```tsx live
<Content>
  <UnorderedList>
    <ListItem textColor="primary">Primary item</ListItem>
    <ListItem textColor="success">Success item</ListItem>
    <ListItem textColor="warning">Warning item</ListItem>
    <ListItem textColor="danger">Danger item</ListItem>
  </UnorderedList>
</Content>
```

### Custom Value in Ordered List

Use the `value` prop to set a custom number in an ordered list.

```tsx live
<Content>
  <OrderedList>
    <ListItem>First item</ListItem>
    <ListItem value={10}>Tenth item (custom value)</ListItem>
    <ListItem>Eleventh item</ListItem>
  </OrderedList>
</Content>
```

### All Colors

Display list items in all Bulma theme colors.

```tsx live
<Content>
  <UnorderedList>
    <ListItem textColor="primary">Primary</ListItem>
    <ListItem textColor="link">Link</ListItem>
    <ListItem textColor="info">Info</ListItem>
    <ListItem textColor="success">Success</ListItem>
    <ListItem textColor="warning">Warning</ListItem>
    <ListItem textColor="danger">Danger</ListItem>
  </UnorderedList>
</Content>
```

### Spaced List Items

Use margin helpers for custom spacing between items.

```tsx live
<Content>
  <UnorderedList>
    <ListItem mb="3">Item with extra bottom margin</ListItem>
    <ListItem mb="3">Another spaced item</ListItem>
    <ListItem>Last item</ListItem>
  </UnorderedList>
</Content>
```

### In Ordered List

ListItem works the same way in ordered lists.

```tsx live
<Content>
  <OrderedList>
    <ListItem>First item</ListItem>
    <ListItem textColor="success">Second item (success)</ListItem>
    <ListItem>Third item</ListItem>
  </OrderedList>
</Content>
```

---

## Accessibility

- **Semantic Markup:** Using proper `` elements inside `` or `` ensures correct accessibility semantics.
- **Color Contrast:** When using colored text or backgrounds, ensure sufficient contrast for readability.
- **Screen Readers:** List items are announced as part of the list structure by screen readers.

:::info
Always use `ListItem` inside `UnorderedList` or `OrderedList` for proper semantic structure.
:::

---

## Related Components

- [`UnorderedList`](./unorderedlist.md): Parent component for bulleted lists.
- [`OrderedList`](./orderedlist.md): Parent component for numbered lists.
- [`Content`](./content.md): For rich typographic content including lists.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [MDN: li element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li)
- [Storybook: ListItem Stories](https://bestax.io/storybook/?path=/story/elements-listitem--default)

---

## Notification


## Overview

The `Notification` component is a Bulma-styled alert/message area for providing feedback, warnings, or information to users. It supports color themes, light variants, an optional close (delete) button, custom content, and all Bulma helper props for spacing, etc.

:::info
Notifications are perfect for status updates, alerts, and dismissible feedback in your UI.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                        |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------- |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                            |
| `color`     | `Bulma color` (e.g. `'primary'`, `'info'`, etc.)                                                                                                                                                                                                                                         | —       | Bulma color modifier for the notification.         |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                                 |
| `isLight`   | `boolean`                                                                                                                                                                                                                                                                                | —       | Use the light color variant.                       |
| `hasDelete` | `boolean`                                                                                                                                                                                                                                                                                | —       | Shows a close (delete) button in the notification. |
| `onDelete`  | `() => void`                                                                                                                                                                                                                                                                             | —       | Callback fired when the delete button is clicked.  |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Content inside the notification.                   |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                              |         | (See [Helper Props](../helpers/usebulmaclasses))   |

---

## Usage

### Default Notification

The default usage of the `Notification` component displays a simple alert box for status messages, feedback, or information. Use this for general notifications that don't require color coding.

```tsx live
<Notification>This is a default notification.</Notification>
```

### Primary Notification

To emphasize important messages, set the `color` prop to `primary`. This applies the Bulma primary color styling, making the notification stand out for high-priority information. Use `color` with values like `primary`, `info`, `success`, `warning`, or `danger` to match the context of your message.

```tsx live
<Notification color="primary">This is a primary notification.</Notification>
```

### Light Variant

For a softer, less prominent notification, add the `isLight` prop. This creates a pastel version of the chosen `color`, ideal for subtle alerts or background information that should not dominate the interface but still be color-coded.

```tsx live
<Notification color="primary" isLight>
  This is a light primary notification.
</Notification>
```

### Success, Warning, Danger, Info, and Link

You can use the `color` prop with values like `success`, `warning`, `danger`, `info`, or `link` to visually differentiate notifications based on their purpose. This helps users quickly recognize the type of message being displayed.

```tsx live
<>
  <Notification color="success">This is a success notification.</Notification>
  <Notification color="warning">This is a warning notification.</Notification>
  <Notification color="danger">This is a danger notification.</Notification>
  <Notification color="info">This is an info notification.</Notification>
  <Notification color="link">This is a link notification.</Notification>
</>
```

### With Dismiss Button

To make notifications dismissible, set the `hasDelete` prop to show a close button. Combine with the `onDelete` callback to control visibility, such as hiding the notification when the button is clicked. This pattern is useful for temporary alerts or feedback that users can clear from the interface.

```tsx live
function example() {
  const [visible, setVisible] = React.useState(true);

  return (
    <>
      {visible && (
        <Notification hasDelete onDelete={() => setVisible(false)}>
          Click the delete button to dismiss this notification.
        </Notification>
      )}
    </>
  );
}
```

### With Margin

You can apply Bulma helper props such as `m` (margin) directly to the `Notification` component. For example, `m="4"` adds a margin of 4 units, allowing you to control spacing around notifications for better layout and visual separation.

```tsx live
<Notification m="4">This notification has a margin.</Notification>
```

### Custom Content

The `Notification` component supports any custom content as its children. You can include elements like ``, links, or other inline components to create rich, informative messages tailored to your application's needs.

```tsx live
<Notification color="warning">
  Warning! This notification contains{' '}
  <Link href="#">custom content</Link>.
</Notification>
```

---

## Accessibility

- **Delete button:** Includes `aria-label="Close notification"` for screen readers.
- **Keyboard:** The delete button is focusable and can be activated by keyboard.
- **Content:** Use semantic HTML within the notification for best accessibility.

:::tip
Always provide clear, actionable text inside notifications.
:::

---

## Related Components

- [`Delete`](./delete.md): The close button used in notifications.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Notification Documentation](https://bulma.io/documentation/elements/notification/)
- [Storybook: Notification Stories](https://bestax.io/storybook/?path=/story/elements-notification--default)

---

## OrderedList


## Overview

The `OrderedList` component renders a styled ordered list (``) element with Bulma helper class integration. Use it with `ListItem` components to create numbered lists with consistent styling. Supports all standard `` attributes like `type`, `start`, and `reversed`.

:::info
The OrderedList component is a thin wrapper around the HTML `` element, providing consistent Bulma styling and helper class support.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `type`      | `'1'` \| `'a'` \| `'A'` \| `'i'` \| `'I'`                                                                                                                                                                                                                                                | `'1'`   | The numbering type for the list.                 |
| `start`     | `number`                                                                                                                                                                                                                                                                                 | —       | The starting number for the list.                |
| `reversed`  | `boolean`                                                                                                                                                                                                                                                                                | —       | Whether to reverse the list numbering.           |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                               |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | List items to render inside the list.            |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                               |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

:::info Wrap Lists in Content for Traditional Styling
Without a [`Content`](./content.md) wrapper, Bulma renders lists without the traditional margin, padding, and list-style markers (bullets, numbers). Wrap your lists in `<Content>` to get the expected typographic list appearance.
:::

### Default List

The default usage of the `OrderedList` component with numbered items.

```tsx live
<Content>
  <OrderedList>
    <ListItem>First item</ListItem>
    <ListItem>Second item</ListItem>
    <ListItem>Third item</ListItem>
  </OrderedList>
</Content>
```

### Alphabetic Lowercase

Use `type="a"` for lowercase alphabetic numbering.

```tsx live
<Content>
  <OrderedList type="a">
    <ListItem>First item</ListItem>
    <ListItem>Second item</ListItem>
    <ListItem>Third item</ListItem>
  </OrderedList>
</Content>
```

### Alphabetic Uppercase

Use `type="A"` for uppercase alphabetic numbering.

```tsx live
<Content>
  <OrderedList type="A">
    <ListItem>First item</ListItem>
    <ListItem>Second item</ListItem>
    <ListItem>Third item</ListItem>
  </OrderedList>
</Content>
```

### Roman Numerals

Use `type="I"` for uppercase Roman numerals or `type="i"` for lowercase.

```tsx live
<Content>
  <OrderedList type="I">
    <ListItem>First item</ListItem>
    <ListItem>Second item</ListItem>
    <ListItem>Third item</ListItem>
  </OrderedList>
</Content>
```

### Custom Starting Number

Use the `start` prop to begin numbering from a specific value.

```tsx live
<Content>
  <OrderedList start={5}>
    <ListItem>Fifth item</ListItem>
    <ListItem>Sixth item</ListItem>
    <ListItem>Seventh item</ListItem>
  </OrderedList>
</Content>
```

### Reversed Order

Use the `reversed` prop to count down instead of up.

```tsx live
<Content>
  <OrderedList reversed>
    <ListItem>Third item (shown as 3)</ListItem>
    <ListItem>Second item (shown as 2)</ListItem>
    <ListItem>First item (shown as 1)</ListItem>
  </OrderedList>
</Content>
```

### Colored List

Apply text color to all list items.

```tsx live
<Content>
  <OrderedList textColor="primary">
    <ListItem>First item</ListItem>
    <ListItem>Second item</ListItem>
    <ListItem>Third item</ListItem>
  </OrderedList>
</Content>
```

### Nested Lists

Create nested ordered lists with different numbering types.

```tsx live
<Content>
  <OrderedList>
    <ListItem>First item</ListItem>
    <ListItem>
      Second item with nested list
      <OrderedList type="a">
        <ListItem>Nested item a</ListItem>
        <ListItem>Nested item b</ListItem>
      </OrderedList>
    </ListItem>
    <ListItem>Third item</ListItem>
  </OrderedList>
</Content>
```

---

## Accessibility

- **List Structure:** Screen readers announce ordered lists with their numbering, helping users understand sequential content.
- **Semantic Markup:** Using proper `` and `` elements ensures accessibility for all users.
- **Numbering Type:** The `type` attribute is announced by most screen readers, providing context about the list format.

:::info
Use `OrderedList` when the order of items is significant, such as steps in a process or ranked items.
:::

---

## Related Components

- [`UnorderedList`](./unorderedlist.md): For bulleted/unordered lists.
- [`ListItem`](./listitem.md): Individual list item component.
- [`Content`](./content.md): For rich typographic content including lists.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [MDN: ol element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol)
- [Storybook: OrderedList Stories](https://bestax.io/storybook/?path=/story/elements-orderedlist--default)

---

## Paragraph


## Overview

The `Paragraph` component renders a styled `` element with Bulma helper class integration. Use it for text content that benefits from Bulma's typography utilities, including text color, size, alignment, weight, and spacing.

:::info
The Paragraph component is a thin wrapper around the HTML `` element, providing consistent Bulma styling and helper class support for text content.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                               |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Content to render inside the paragraph.          |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                                |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

:::info Wrap Paragraphs in Content for Traditional Spacing
Without a [`Content`](./content.md) wrapper, Bulma resets paragraph margins. Wrap your paragraphs in `<Content>` to get the expected spacing between `` tags.
:::

### Default Paragraph

The default usage of the `Paragraph` component renders a standard paragraph element.

```tsx live
<Paragraph>
  This is a default paragraph. It contains some sample text to demonstrate the
  component.
</Paragraph>
```

### Primary Color Paragraph

Set the text color using the `textColor` prop for emphasis.

```tsx live
<Paragraph textColor="primary">
  This paragraph has primary colored text.
</Paragraph>
```

### Centered Text

Use the `textAlign` prop to center the text.

```tsx live
<Paragraph textAlign="centered">This paragraph is centered.</Paragraph>
```

### Paragraph with Background

Add a background color and padding to create a callout effect.

```tsx live
<Paragraph bgColor="dark" textColor="white" p="3">
  This paragraph has a dark background.
</Paragraph>
```

### Large Text

Use the `textSize` prop to increase the font size.

```tsx live
<Paragraph textSize="3">This is a large paragraph.</Paragraph>
```

### Small Text

Use the `textSize` prop with a larger number for smaller text.

```tsx live
<Paragraph textSize="7">This is a small paragraph.</Paragraph>
```

### Justified Text

Use `textAlign="justified"` for text that spans the full width.

```tsx live
<Block style={{ maxWidth: '400px' }}>
  <Paragraph textAlign="justified">
    This paragraph has justified text alignment. Lorem ipsum dolor sit amet,
    consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et
    dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation
    ullamco laboris.
  </Paragraph>
</Block>
```

### All Colors

Display paragraphs in all Bulma theme colors.

```tsx live
<Block display="flex" flexDirection="column" gap="2">
  <Paragraph textColor="primary">Primary paragraph</Paragraph>
  <Paragraph textColor="link">Link paragraph</Paragraph>
  <Paragraph textColor="info">Info paragraph</Paragraph>
  <Paragraph textColor="success">Success paragraph</Paragraph>
  <Paragraph textColor="warning">Warning paragraph</Paragraph>
  <Paragraph textColor="danger">Danger paragraph</Paragraph>
</Block>
```

### Stacked Paragraphs

Wrap paragraphs in `Content` to get natural spacing between them without manual margin props.

```tsx live
<Content style={{ maxWidth: '500px' }}>
  <Paragraph>
    First paragraph. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  </Paragraph>
  <Paragraph>
    Second paragraph. Sed do eiusmod tempor incididunt ut labore et dolore magna
    aliqua.
  </Paragraph>
  <Paragraph>
    Third paragraph. Ut enim ad minim veniam, quis nostrud exercitation.
  </Paragraph>
</Content>
```

### Highlighted Paragraph

Combine background and text colors for a callout or highlight effect.

```tsx live
<Paragraph bgColor="dark" textColor="white" p="4">
  This is a highlighted paragraph with dark background.
</Paragraph>
```

---

## Accessibility

- **Semantic Structure:** Use paragraphs to wrap distinct blocks of text for proper document structure.
- **Color Contrast:** Ensure sufficient contrast between text and background colors for readability.
- **Heading Order:** Paragraphs should follow proper heading hierarchy in your document.

:::info
For semantic emphasis within paragraphs, use `` (Strong) or `` (Emphasis) components.
:::

---

## Related Components

- [`Span`](./span.md): For inline styled text.
- [`Strong`](./strong.md): For semantically important bold text.
- [`Emphasis`](./emphasis.md): For semantically emphasized italic text.
- [`Content`](./content.md): For rich typographic content.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Typography Helpers](https://bulma.io/documentation/helpers/typography-helpers/)
- [Storybook: Paragraph Stories](https://bestax.io/storybook/?path=/story/elements-paragraph--default)

---

## Pre


## Overview

The `Pre` component renders a styled `<pre>` element with Bulma helper class integration. Use it for multi-line code blocks, terminal output, ASCII art, or any content where whitespace formatting must be preserved.

:::info
Often used together with the `Code` component for semantically correct code blocks: `<Pre><Code>...</Code></Pre>`.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                               |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Preformatted content to render.                  |
| ...         | All standard `<pre>` and Bulma helper props                                                                                                                                                                                                                                              |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Pre

The default usage preserves whitespace and line breaks.

```tsx live
<Pre>{`function hello() {
  console.log("Hello, World!");
}`}</Pre>
```

### With Code Element

Combine with `Code` for semantically correct code blocks.

```tsx live
<Pre>
  <Code>{`const greeting = "Hello";
const name = "World";
console.log(\`\${greeting}, \${name}!\`);`}</Code>
</Pre>
```

### Dark Background

Create a terminal-like appearance with dark background and light text.

```tsx live
<Pre bgColor="dark" textColor="white" p="4">{`pnpm add @allxsmith/bestax-bulma
pnpm build`}</Pre>
```

### Light Background

Use a light background for a subtle code block.

```tsx live
<Pre bgColor="light" p="4">{`{
  "name": "my-app",
  "version": "1.0.0"
}`}</Pre>
```

### Terminal Output

Style terminal output with appropriate colors.

```tsx live
<Pre bgColor="dark" textColor="success" p="4">{`$ pnpm build
> @allxsmith/bestax-bulma@2.0.0 build
> tsc && vite build

vite v6.0.0 building for production...
✓ 123 modules transformed.
dist/index.js  45.23 kB
✓ built in 2.34s`}</Pre>
```

### Multiple Code Blocks

Display different code examples side by side.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <Pre bgColor="light" p="3">
    <Code>{`// JavaScript
const add = (a, b) => a + b;`}</Code>
  </Pre>
  <Pre bgColor="light" p="3">
    <Code>{`// TypeScript
const add = (a: number, b: number): number => a + b;`}</Code>
  </Pre>
</Block>
```

### Primary Accent

Use color for comments or special sections.

```tsx live
<Pre textColor="primary" p="3">{`// Important configuration
const config = {
  debug: true,
  verbose: true
};`}</Pre>
```

---

## Accessibility

- **Whitespace Preservation:** The `<pre>` element preserves all whitespace, which is important for code formatting.
- **Scrolling:** Consider horizontal scrolling for long lines to prevent layout issues.
- **Screen Readers:** Preformatted text is typically announced as such by screen readers.

:::info
For code blocks, wrap content in both `<Pre>` and `<Code>` for proper semantics: `<Pre><Code>...</Code></Pre>`.
:::

---

## Related Components

- [`Code`](./code.md): For inline code snippets (often used inside Pre).
- [`Figure`](./figure.md): For code figures with captions.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [MDN: pre element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/pre)
- [Storybook: Pre Stories](https://bestax.io/storybook/?path=/story/elements-pre--default)

---

## Progress


## Overview

The `Progress` component displays a Bulma-styled progress bar. It supports color and size modifiers, value/max attributes, custom content, and all Bulma helper props for spacing and layout.

:::info
Use `Progress` for visualizing task completion, loading states, or quantitative user feedback.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                             | Default | Description                                      |
| ----------- | ------------------------------------------------ | ------- | ------------------------------------------------ |
| `className` | `string`                                         | —       | Additional CSS classes.                          |
| `color`     | `Bulma color` (e.g. `'primary'`, `'info'`, etc.) | —       | Bulma color modifier for the progress bar.       |
| `size`      | `'small' \| 'medium' \| 'large'`                 | —       | Size modifier for the progress bar.              |
| `value`     | `number`                                         | —       | Current value of the progress bar.               |
| `max`       | `number`                                         | —       | Maximum value of the progress bar.               |
| `children`  | `React.ReactNode`                                | —       | Optional custom content inside the progress bar. |
| ...         | All standard `<progress>` and Bulma helper props |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Progress

The default usage of the `Progress` component displays a horizontal progress bar. Set the `value` and `max` props to indicate completion percentage or progress toward a goal.

```tsx live
<Progress value={50} max={100} />
```

### Colored Progress

Set the `color` prop to visually distinguish different types of progress. Use color variants like `primary`, `success`, `warning`, `danger`, `info`, or `link` to match the context of the task or status.

```tsx live
<>
  <Progress color="primary" value={75} max={100} />
  <Progress color="success" value={90} max={100} />
  <Progress color="warning" value={30} max={100} />
  <Progress color="danger" value={10} max={100} />
  <Progress color="info" value={60} max={100} />
  <Progress color="link" value={80} max={100} />
</>
```

### Sizing

Adjust the size of the progress bar using the `size` prop. Options include `small`, `medium`, or `large` to fit the design requirements of your application.

```tsx live
<>
  <Progress size="small" value={50} max={100} />
  <Progress size="medium" value={50} max={100} />
  <Progress size="large" value={50} max={100} />
</>
```

### With Margin

Utilize Bulma's spacing helpers by adding margin props like `m="4"` to control the progress bar's margin. This example applies a margin of 4 units.

```tsx live
<Progress value={50} max={100} m="4" />
```

### Indeterminate Progress

For tasks with unknown progress, use the indeterminate state by omitting the `value` prop. This example shows a primary colored indeterminate progress bar.

```tsx live
<Progress color="primary" max={100} />
```

### Custom Content

The `Progress` component allows for custom content inside the progress bar. This example shows how to display text content indicating the completion percentage.

```tsx live
<Progress value={50} max={100}>
  50% Complete
</Progress>
```

### Multiple Indeterminate

Easily create multiple indeterminate progress bars with different sizes and colors. This example demonstrates a combination of small, medium, and large indeterminate bars.

```tsx live
<>
  <Progress size="small" color="primary" max={100} />
  <Progress color="danger" max={100} />
  <Progress size="medium" color="dark" max={100} />
  <Progress size="large" color="info" max={100} />
</>
```

---

## Accessibility

- **Role:** The `<progress>` element is natively accessible.
- **Labeling:** Always provide context for screen readers (e.g., with `aria-label` or visible text).
- **Indeterminate:** Omit the `value` prop for indeterminate progress bars.

:::warning
Ensure your progress bars have sufficient color contrast for users with visual impairments.
:::

---

## Related Components

- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Progress Documentation](https://bulma.io/documentation/elements/progress/)
- [Storybook: Progress Stories](https://bestax.io/storybook/?path=/story/elements-progress--default)

---

## Skeleton


## Overview

The `Skeleton` component provides a Bulma-styled skeleton loader for React applications, useful for indicating that content is loading. It can be used as a placeholder for headings, paragraphs, blocks, or custom content.

:::info
Use `Skeleton` to improve perceived performance and give users a visual cue that content is being fetched.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                 | Default   | Description                                        |
| ----------- | ------------------------------------ | --------- | -------------------------------------------------- |
| `className` | `string`                             | —         | Additional CSS classes.                            |
| `variant`   | `'block' \| 'lines'`                 | `'block'` | Skeleton variant: block (single block) or lines.   |
| `lines`     | `number`                             | `3`       | Number of lines (only for `lines` variant).        |
| `children`  | `React.ReactNode`                    | —         | Content inside the block (only for block variant). |
| ...         | All standard `` HTML attributes |           | Passed through to the root element.                |

---

## Usage

### Default Skeleton

The default usage of the `Skeleton` component renders a block placeholder, ideal for simulating loading content such as cards, images, or sections.

```tsx live
<Skeleton />
```

### Skeleton Text

Use the `children` prop to display placeholder text or content inside the skeleton block. This is useful for simulating paragraphs or multi-line content while data is loading.

```tsx live
<Skeleton>
  "Quando in rerum natura homines aequales creantur, ab ipso Creatore quibusdam
  iuribus inalienabilibus donantur, inter quae sunt Vita, Libertas et quaerenda
  felicitas. Quoties aliquod regimen haec iura destruere conatur, populus habet
  potestatem tale regimen abrogare et novum constituere, quod iuribus suis
  tutandis aptissimum videatur. Prudentia quidem dictat vetera regimina levibus
  de causis non mutanda esse; sed cum diuturnus abusus ad despotismum vergit,
  ius est, immo officium, talia regimina exuere et novas custodes securitatis
  futurae constituere."
</Skeleton>
```

### Lines Skeleton

The `lines` variant of the `Skeleton` component renders multiple line placeholders, perfect for simulating text content loading. Use the `lines` prop to specify the number of lines.

```tsx live
<Skeleton variant="lines" lines={5} />
```

---

### Skeleton Examples from useBulmaClasses.stories.tsx

These show how the `skeleton` Bulma helper can be applied to various components using the `skeleton` prop and `useBulmaClasses`. The skeleton state toggles on an interval in Storybook.

#### Skeleton Button

Demonstrates a button with a skeleton loader, useful for indicating an action is in progress.

```tsx live
<Button skeleton color="dark">
  Skeleton Button
</Button>
```

#### Skeleton Buttons Group

A group of buttons with skeleton loaders, ideal for simulating multiple actions loading simultaneously.

```tsx live
<Buttons>
  <Button skeleton color="dark">
    Skeleton
  </Button>
  <Button skeleton color="dark">
    Skeleton
  </Button>
  <Button skeleton color="dark">
    Skeleton
  </Button>
</Buttons>
```

#### Skeleton Icon

An icon with a skeleton loader, perfect for indicating an icon's action is loading.

```tsx live
<Icon name="star" skeleton ariaLabel="Star icon skeleton" size="medium" />
```

#### Skeleton Image

An image with a skeleton loader, great for simulating image loading.

```tsx live
<Image skeleton src="/img/react-logo.png" alt="Skeleton image" size="128x128" />
```

#### Skeleton Media

Media object with a skeleton loader, useful for indicating media content is loading.

```tsx live
<Media skeleton>
  <Media.Left>
    <Image
      skeleton
      as="p"
      size="64x64"
      src="https://bulma.io/assets/images/placeholders/128x128.png"
      alt=""
    />
  </Media.Left>
  <Media.Content>
    <Content>
      <Paragraph>
        Skeleton Name <small>@skelly</small> <small>1m</small>
        
        This is a skeleton media example.
      </Paragraph>
    </Content>
  </Media.Content>
</Media>
```

#### Skeleton Notification

A notification with a skeleton loader, ideal for indicating a message or alert is loading.

```tsx live
<Notification skeleton>Skeleton notification message.</Notification>
```

#### Skeleton Tag

A tag with a skeleton loader, great for simulating tag or category loading.

```tsx live
<Tag skeleton size="medium">
  Skeleton Tag
</Tag>
```

#### Skeleton Title

A title with a skeleton loader, useful for indicating a section or heading is loading.

```tsx live
<Title skeleton size="2">
  Skeleton Title
</Title>
```

#### Skeleton SubTitle

A subtitle with a skeleton loader, perfect for simulating secondary heading loading.

```tsx live
<SubTitle skeleton size="4">
  Skeleton SubTitle
</SubTitle>
```

#### Skeleton Input

An input field with a skeleton loader, ideal for indicating form input is loading.

```tsx live
<Input skeleton placeholder="Skeleton Input" />
```

#### Skeleton TextArea

A textarea with a skeleton loader, useful for simulating multi-line text input loading.

```tsx live
<TextArea skeleton placeholder="Skeleton TextArea" rows={3} />
```

---

## Accessibility

- **Role:** Consider using `aria-busy="true"` on container elements to indicate loading state.
- **Label:** Optionally use `aria-label="Loading..."` or similar for better screen reader support.
- **Focus:** Skeletons should not be focusable and should be replaced with real content as soon as data is available.

:::tip
Skeleton loaders provide a visual cue for loading but should not block navigation or accessibility.
:::

---

## Related Components

The following components support the `skeleton` property for Bulma skeleton loaders:

- [`Button`](./button.md)
- [`Buttons`](./buttons.md)
- [`Icon`](./icon.md)
- [`Image`](./image.md)
- [`Media`](../layout/media.md)
- [`Notification`](./notification.md)
- [`Tag`](./tag.md)
- [`Title`](./title.md)
- [`SubTitle`](./subtitle.md)
- [`Input`](../form/input.md)
- [`TextArea`](../form/textarea.md)
- [`useBulmaClasses`](../helpers/usebulmaclasses.md): The helper hook that enables the `skeleton` prop for any compatible component.

---

## Additional Resources

- [Bulma Skeleton Documentation](https://bulma.io/documentation/features/skeletons/)
- [Storybook: Skeleton Stories](https://bestax.io/storybook/?path=/story/elements-skeleton--default)

---

## Span


## Overview

The `Span` component renders a styled inline `` element with Bulma helper class integration. Use it for highlighting text, applying inline styles, or wrapping content that needs Bulma's typography and color utilities without affecting the document flow.

:::info
The Span component is a thin wrapper around the HTML `` element, providing consistent Bulma styling and helper class support for inline content.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                               |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Content to render inside the span.               |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                             |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Span

The default usage of the `Span` component renders plain inline content.

```tsx live
Default Span
```

### Primary Color Span

Set the text color using the `textColor` prop to highlight inline text.

```tsx live
Primary Text
```

### Success Color Span

Use semantic colors to convey meaning.

```tsx live
Success Text
```

### Span with Background

Add a background color and padding to create a highlight effect.

```tsx live

  Highlighted Text

```

### Large Text Span

Use the `textSize` prop to increase the font size of inline content.

```tsx live
Large Span
```

### Bold Span

Apply bold text weight for emphasis.

```tsx live
Bold Span
```

### All Colors

Display spans in all Bulma theme colors.

```tsx live
<Block display="flex" flexDirection="column" gap="2">
  Primary Span
  Link Span
  Info Span
  Success Span
  Warning Span
  Danger Span
</Block>
```

### Inline with Text

Spans work seamlessly inline within paragraphs.

```tsx live
<Paragraph>
  This paragraph contains a colored span and a{' '}
  bold span for emphasis.
</Paragraph>
```

### Highlighted Text

Combine background and text colors for a marker-like highlight effect.

```tsx live
<Paragraph>
  This sentence has{' '}
  
    highlighted text
  {' '}
  to draw attention.
</Paragraph>
```

---

## Accessibility

- **Semantic Meaning:** The `` element has no semantic meaning. Use it only for styling purposes.
- **Color Contrast:** Ensure sufficient contrast between text and background colors for readability.
- **Screen Readers:** Content inside spans is read normally by screen readers.

:::info
For text that has semantic importance, consider using `` (Strong) or `` (Emphasis) components instead.
:::

---

## Related Components

- [`Strong`](./strong.md): For semantically important bold text.
- [`Emphasis`](./emphasis.md): For semantically emphasized italic text.
- [`Paragraph`](./paragraph.md): For text paragraphs.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Typography Helpers](https://bulma.io/documentation/helpers/typography-helpers/)
- [Storybook: Span Stories](https://bestax.io/storybook/?path=/story/elements-span--default)

---

## Strong


## Overview

The `Strong` component renders a styled `` element with Bulma helper class integration. Use it for text that has strong importance, seriousness, or urgency. The `` element carries semantic meaning for screen readers and search engines.

:::info
For visual-only bold styling without semantic meaning, use the `Span` component with `textWeight="bold"` instead.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                               |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Content to render inside the strong element.     |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                           |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Strong

The default usage renders bold text with semantic importance.

```tsx live
Important text
```

### Colored Strong

Apply text color for additional emphasis.

```tsx live
Primary strong text
```

### Danger Strong

Use danger color for warnings or critical information.

```tsx live
Important warning!
```

### Strong with Background

Add background color and padding for a highlight effect.

```tsx live

  Highlighted strong text

```

### Inline with Text

Strong text works naturally inline within paragraphs.

```tsx live
<Paragraph>
  This is a paragraph with strong text in the middle. The
  strong text indicates important content.
</Paragraph>
```

### All Colors

Display strong text in all Bulma theme colors.

```tsx live
<Block display="flex" flexDirection="column" gap="2">
  Primary strong
  Link strong
  Info strong
  Success strong
  Warning strong
  Danger strong
</Block>
```

### Callout Pattern

A common pattern for callouts with a strong lead word.

```tsx live
<Paragraph>
  Note: This is a pattern commonly used for callouts where the
  lead word is strong to draw attention.
</Paragraph>
```

---

## Accessibility

- **Semantic Importance:** Screen readers typically announce `` content with additional emphasis.
- **Appropriate Use:** Use `` for content that is truly important, not just for visual styling.
- **Color Contrast:** When adding color, ensure sufficient contrast for readability.

:::info
The `` element indicates strong importance. For visual-only bold styling, use CSS or the `Span` component with `textWeight="bold"`.
:::

---

## Related Components

- [`Emphasis`](./emphasis.md): For semantically emphasized italic text.
- [`Span`](./span.md): For styled inline text without semantic meaning.
- [`Paragraph`](./paragraph.md): For text paragraphs.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [MDN: strong element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/strong)
- [Storybook: Strong Stories](https://bestax.io/storybook/?path=/story/elements-strong--default)

---

## SubTitle


## Overview

The `SubTitle` component renders a Bulma-styled subtitle (secondary heading), supporting sizes `1-6` and rendering as any heading or paragraph element (`h1-h6`, `p`). Use it for subheadings, section titles, and supporting text.

:::info
`SubTitle` helps create clarity in content structure, especially when paired with `Title`.
:::

---

## Import

```tsx

```

---

## Props

| Prop          | Type                                                                                                                                                                                                                                                                                     | Default | Description                                              |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------- |
| `className`   | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                                  |
| `size`        | `'1' \| '2' \| '3' \| '4' \| '5' \| '6'`                                                                                                                                                                                                                                                 | —       | Size of the subtitle (Bulma sizes).                      |
| `as`          | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6' \| 'p'`                                                                                                                                                                                                                                    | `'h1'`  | HTML element to render as.                               |
| `hasSkeleton` | `boolean`                                                                                                                                                                                                                                                                                | —       | Applies the `has-skeleton` class to part of the content. |
| `skeleton`    | `boolean`                                                                                                                                                                                                                                                                                | —       | Applies the `is-skeleton` class to the entire component. |
| `children`    | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Subtitle content.                                        |
| `textColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                                       |
| `bgColor`     | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                                 |
| ...           | All standard heading/paragraph and Bulma helper props                                                                                                                                                                                                                                    |         | (See [Helper Props](../helpers/usebulmaclasses))         |

---

## Usage

### Default SubTitle

A basic `SubTitle` renders a secondary heading. Use this for subheadings or supporting text below a main title.

```tsx live
<SubTitle>Default SubTitle</SubTitle>
```

### Has Skeleton

Set the `hasSkeleton` prop to apply a skeleton effect to part of the subtitle, useful for partial loading states.

```tsx live
<SubTitle hasSkeleton>SubTitle with Skeleton Effect</SubTitle>
```

`hasSkeleton` will only turn a small part of the content into a skeleton, typically for partial loading effects.

### Is Skeleton

Set the `skeleton` prop to apply a skeleton effect to the entire subtitle, indicating that the whole heading is loading.

```tsx live
<SubTitle skeleton>SubTitle Skeleton Effect</SubTitle>
```

`skeleton` applies the `is-skeleton` class to the entire subtitle, making the whole heading appear as a skeleton placeholder.

### Different Sizes

Adjust the `size` prop to change the subtitle size, with available options from `1` to `6`, corresponding to Bulma's size classes.

```tsx live
<>
  <SubTitle size="2">SubTitle Size 2</SubTitle>
  <SubTitle size="4">SubTitle Size 4</SubTitle>
</>
```

### With Margin

Utilize margin props like `m="4"` to add spacing around the subtitle, helping to separate it from other content.

```tsx live
<SubTitle m="4">SubTitle with Margin</SubTitle>
```

### As Paragraph

Render the subtitle as a paragraph element by setting the `as` prop to `"p"`. This is useful for body text that requires emphasis.

```tsx live
<SubTitle as="p" size="3">
  SubTitle as Paragraph
</SubTitle>
```

### All Sizes

Quickly render all subtitle sizes from `1` to `6` using a map function. This is helpful for demonstrating or testing styles.

```tsx live
<>
  {['1', '2', '3', '4', '5', '6'].map(size => (
    <SubTitle key={size} size={size}>
      SubTitle Size {size}
    </SubTitle>
  ))}
</>
```

### Title and Subtitle Pairings

Combine `Title` and `SubTitle` components for a structured heading and subheading layout. This is ideal for section titles.

```tsx live
<Block>
  <Title as="p" size="1">
    Title 1
  </Title>
  <SubTitle as="p" size="3">
    Subtitle 3
  </SubTitle>
</Block>
```

---

## Accessibility

- **Semantic HTML:** Use appropriate heading levels for document structure.
- **Screen readers:** Subtitles should be used in conjunction with titles for clarity.

:::tip
`SubTitle` is visually styled as a heading, but its semantic level depends on the `as` prop.
:::

---

## Related Components

- [`Title`](./title.md): For main headings.
- [`Block`](./block.md): For spacing and grouping content.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Title Documentation (Subtitle)](https://bulma.io/documentation/elements/title/#subtitle)
- [Storybook: SubTitle Stories](https://bestax.io/storybook/?path=/story/elements-subtitle--default)

---

## Table


## Overview

The `Table` component and its subcomponents provide a highly composable, Bulma-styled table system for React. You get full access to Bulma’s table features—borders, stripes, narrow cells, hover effects, responsive scroll, cell/row coloring, and more—using idiomatic React patterns. All Bulma helper props for spacing and color are supported.

:::info
Use the full suite: `Table`, `Thead`, `Tbody`, `Tfoot`, `Tr`, `Th`, and `Td` for maximum flexibility and Bulma compatibility.
:::

---

## Import

```tsx

  Table,
  Thead,
  Tbody,
  Tfoot,
  Tr,
  Th,
  Td,
} from '@allxsmith/bestax-bulma';
```

---

## Props

### Table

| Prop           | Type                                          | Default | Description                                               |
| -------------- | --------------------------------------------- | ------- | --------------------------------------------------------- |
| `className`    | `string`                                      | —       | Additional CSS classes.                                   |
| `isBordered`   | `boolean`                                     | —       | Adds borders to all cells.                                |
| `isStriped`    | `boolean`                                     | —       | Adds zebra-striping to rows.                              |
| `isNarrow`     | `boolean`                                     | —       | Makes the table more compact.                             |
| `isHoverable`  | `boolean`                                     | —       | Adds a hover effect on rows.                              |
| `isFullwidth`  | `boolean`                                     | —       | Makes the table span the full width of its parent.        |
| `isResponsive` | `boolean`                                     | —       | Makes the table horizontally scrollable on small screens. |
| `children`     | `ReactNode`                                   | —       | Table content (should use subcomponents).                 |
| ...            | All standard `` and Bulma helper props |         | (See [Helper Props](../helpers/usebulmaclasses))          |

### Thead / Tbody / Tfoot

| Prop        | Type                                      | Default | Description                                      |
| ----------- | ----------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                  | —       | Additional CSS classes.                          |
| `children`  | `ReactNode`                               | —       | Section content (typically `Tr` rows).           |
| ...         | All standard props and Bulma helper props |         | (See [Helper Props](../helpers/usebulmaclasses)) |

### Tr

| Prop         | Type                                      | Default | Description                                      |
| ------------ | ----------------------------------------- | ------- | ------------------------------------------------ |
| `className`  | `string`                                  | —       | Additional CSS classes.                          |
| `isSelected` | `boolean`                                 | —       | Adds Bulma's `is-selected` class.                |
| `color`      | `TableColor`                              | —       | Bulma color modifier for the row.                |
| `children`   | `ReactNode`                               | —       | Row content (typically `Th`/`Td`).               |
| ...          | All standard props and Bulma helper props |         | (See [Helper Props](../helpers/usebulmaclasses)) |

### Th

| Prop        | Type                                      | Default | Description                                      |
| ----------- | ----------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                  | —       | Additional CSS classes.                          |
| `isAligned` | `'left' \| 'right' \| 'centered'`         | —       | Text alignment.                                  |
| `width`     | `string \| number`                        | —       | Cell width (e.g., `'100px'`, `100`).             |
| `color`     | `TableColor`                              | —       | Bulma color modifier for the header cell.        |
| `children`  | `ReactNode`                               | —       | Header cell content.                             |
| ...         | All standard props and Bulma helper props |         | (See [Helper Props](../helpers/usebulmaclasses)) |

### Td

| Prop        | Type                                      | Default | Description                                      |
| ----------- | ----------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                  | —       | Additional CSS classes.                          |
| `color`     | `TableColor`                              | —       | Bulma color modifier for the cell.               |
| `children`  | `ReactNode`                               | —       | Cell content.                                    |
| ...         | All standard props and Bulma helper props |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Table

To create a basic table, use the `Table` component along with its subcomponents: `Thead`, `Tbody`, `Tr`, `Th`, and `Td`. This approach provides a clear, semantic structure for your data and leverages Bulma's default table styling. Use this pattern for any standard tabular data display in your application.

```tsx live

  
    
      Name
      Age
      Role
    
  
  
    
      Alice
      30
      Engineer
    
    
      Bob
      28
      Designer
    
  

```

### All Modifiers

Showcase the full range of table customization by combining multiple props on the `Table` component. Use `isBordered` to add borders, `isStriped` for zebra-striping, `isNarrow` for compact cells, `isHoverable` for row hover effects, `isFullwidth` to stretch the table to its container, and `isResponsive` for horizontal scrolling on small screens. These modifiers can be mixed and matched to achieve the exact look and behavior you need.

```tsx live

  
    
      Column 1
      Column 2
    
  
  
    
      Cell 1
      Cell 2
    
    
      Cell 3
      Cell 4
    
  

```

### Responsive Table (horizontal scroll on mobile)

Enable the `isResponsive` prop to make your table horizontally scrollable on small screens. This ensures that wide tables with many columns remain accessible and readable on mobile devices, without breaking the layout or hiding data.

```tsx live

  
    
      {Array.from({ length: 20 }, (_, i) => (
        Column {i + 1}
      ))}
    
  
  
    {Array.from({ length: 2 }, (_, row) => (
      
        {Array.from({ length: 20 }, (_, col) => (
          
            Cell {row + 1}-{col + 1}
          
        ))}
      
    ))}
  

```

### Colored Cells

Apply the `color` prop to individual `Td` cells to use Bulma's color modifiers. This is helpful for highlighting important data, categorizing information, or simply making your tables more visually engaging. You can use colors like `primary`, `success`, `warning`, `danger`, `info`, and more.

```tsx live

  
    
      Cell Color
      Example
    
  
  
    
      Primary
      Primary Colored Cell
    
    
      Success
      Success Colored Cell
    
    {/* ...and so on for link, warning, danger, info, black, dark, light, white */}
  

```

### Highlighted Row

Use the `isSelected` prop on a `Tr` to highlight a specific row. This is ideal for drawing attention to active selections, search results, or rows that require user action.

```tsx live

  
    
      Team
      Wins
      Losses
    
  
  
    
      Ice Wolves
      32
      8
    
    
      Frost Giants
      30
      9
    
  

```

### Custom Alignment and Width

To control the alignment and width of table header cells, use the `isAligned` and `width` props on the `Th` component. Set `isAligned` to `left`, `right`, or `centered` to adjust text alignment, and use `width` with a number or string (e.g., `width={200}` or `width="100px"`) to specify the column width. This is useful for formatting tables with specific layout requirements or for emphasizing certain columns.

```tsx live

  
    
      
        Name
      
      Score
    
  
  
    
      Jane Doe
      98
    
  

```

---

## Accessibility

- **Semantics:** Uses ``, ``, ``, `<tfoot>`, ``, ``, and ``—all proper HTML table elements.
- **Responsive:** When using `isResponsive`, the table is wrapped in a scrollable container.
- **Screen Readers:** Always use `` for header cells, and provide descriptive column headings.

:::tip
For responsive tables, ensure your column headers are clear and concise for small screens.
:::

---

## Related Components

- [`Block`](./block.md): For spacing and grouping tables.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Table Documentation](https://bulma.io/documentation/elements/table/)
- [Storybook: Table Stories](https://bestax.io/storybook/?path=/story/elements-table--default)
  :::

---

## Tag


## Overview

The `Tag` component renders a Bulma-styled label or badge. It supports color, size, rounded, hoverable, and delete (close) variants. Use it for status indicators, categorization, dismissible tokens, or compact UI elements.

:::info
Tags are perfect for highlighting statuses, categories, or adding removable tokens to your UI.
:::

---

## Import

```tsx

```

---

## Props

| Prop          | Type                                                                                                             | Default | Description                                      |
| ------------- | ---------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `className`   | `string`                                                                                                         | —       | Additional CSS classes.                          |
| `color`       | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'black' \| 'dark' \| 'light' \| 'white'` | —       | Bulma color modifier for the tag.                |
| `size`        | `'normal' \| 'medium' \| 'large'`                                                                                | —       | Tag size.                                        |
| `isRounded`   | `boolean`                                                                                                        | —       | Renders a rounded tag.                           |
| `isDelete`    | `boolean`                                                                                                        | —       | Renders a delete-style tag (delete button).      |
| `isHoverable` | `boolean`                                                                                                        | —       | Adds hover effect to the tag.                    |
| `onDelete`    | `() => void`                                                                                                     | —       | Callback for delete tag/button.                  |
| `children`    | `React.ReactNode`                                                                                                | —       | Tag content.                                     |
| ...           | All standard `` and Bulma helper props                                                                     |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Tag

A basic `Tag` renders a simple label. Use this for static status indicators or simple badges.

```tsx live
<Tag>Default Tag</Tag>
```

### Colored Tag

Set the `color` prop to apply a Bulma color modifier, such as `color="primary"`, for visual emphasis or to indicate status.

```tsx live
<Tag color="primary">Primary Tag</Tag>
```

### Medium and Large Tag

Use the `size` prop with values like `size="medium"` or `size="large"` to adjust the tag's size for different UI contexts.

```tsx live
<Tags>
  <Tag size="medium">Medium Tag</Tag>
  <Tag size="large">Large Tag</Tag>
</Tags>
```

### Rounded Tag

Add the `isRounded` prop to render a tag with fully rounded corners, making it stand out as a pill-shaped badge.

```tsx live
<Tag isRounded>Rounded Tag</Tag>
```

### Delete Tag (Button)

Set `isDelete` to render a tag as a delete button. Use the `onDelete` callback to handle removal actions.

```tsx live
<Tag isDelete onDelete={() => alert('Deleted!')} />
```

### With Margin

You can use Bulma helper props like `m="4"` to add margin around the tag for spacing within layouts.

```tsx live
<Tag m="4">Tag with Margin</Tag>
```

### Combined Styles

Combine multiple props such as `color`, `size`, `isRounded`, and spacing helpers to create visually distinct tags.

```tsx live
<Tag color="success" size="medium" isRounded m="2">
  Combined Tag
</Tag>
```

### All Colors

Render a set of tags with different `color` values to display a palette of available Bulma color modifiers. The `isHoverable` prop adds a hover effect to each tag.

```tsx live
<Tags>
  {[
    'primary',
    'link',
    'info',
    'success',
    'warning',
    'danger',
    'black',
    'dark',
    'light',
    'white',
  ].map(color => (
    <Tag key={color} color={color} isHoverable>
      {color.charAt(0).toUpperCase() + color.slice(1)}
    </Tag>
  ))}
</Tags>
```

### Sizes Together

You can combine `color`, `size`, and `isHoverable` props to show all size variants for each color in a single layout.

```tsx live
<Block>
  {['primary', 'success', 'danger'].map(color => (
    <Tags key={color}>
      <Tag color={color} size="normal" isHoverable>
        {color.charAt(0).toUpperCase() + color.slice(1)} Normal
      </Tag>
      <Tag color={color} size="medium" isHoverable>
        {color.charAt(0).toUpperCase() + color.slice(1)} Medium
      </Tag>
      <Tag color={color} size="large" isHoverable>
        {color.charAt(0).toUpperCase() + color.slice(1)} Large
      </Tag>
    </Tags>
  ))}
</Block>
```

### Hoverable Tag

Set `isHoverable` to add a hover effect, making the tag interactive for mouse users.

```tsx live
<Tag color="primary" isHoverable>
  Hoverable Tag
</Tag>
```

### Tag with Delete Component

You can combine `Tag` with the `Delete` component for custom dismissible tags. Use `hasAddons` on the `Tags` container to group them visually.

```tsx live

<Tags hasAddons>
  <Tag color="primary" size="medium">
    Tag with Delete
    <Delete onClick={() => alert('Tag deleted!')} />
  </Tag>
</Tags>;
```

---

## Accessibility

- **Delete buttons:** Use `aria-label` for delete tags for screen readers.
- **Keyboard:** Delete tags are rendered as `<button>`, supporting keyboard activation.
- **Semantics:** Use tags for supplemental information, not as primary headings.

:::tip
Combine `Tag` with `Tags` for grouped, multi-tag UIs.
:::

---

## Related Components

- [`Tags`](./tags.md): For grouping tags.
- [`Delete`](./delete.md): For standalone delete buttons.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Tag Documentation](https://bulma.io/documentation/elements/tag/)
- [Storybook: Tag Stories](https://bestax.io/storybook/?path=/story/elements-tag--default)

---

## Tags


## Overview

The `Tags` component groups multiple `Tag` components together in a horizontal (or multiline) Bulma-styled container. Use it for tag clouds, keyword lists, multi-select UIs, or displaying collections of dismissible tokens.

:::info
Use `Tags` to organize tags with add-on and multiline layouts for a clean, compact UI.
:::

---

## Import

```tsx

```

---

## Props

| Prop          | Type                                        | Default | Description                                      |
| ------------- | ------------------------------------------- | ------- | ------------------------------------------------ |
| `className`   | `string`                                    | —       | Additional CSS classes.                          |
| `hasAddons`   | `boolean`                                   | —       | Group tags together as add-ons (no spacing).     |
| `isMultiline` | `boolean`                                   | —       | Allow tags to wrap onto multiple lines.          |
| `children`    | `ReactNode`                                 | —       | Tag elements to render inside the container.     |
| ...           | All standard `` and Bulma helper props |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Tags

A basic `Tags` container groups several `Tag` components in a single line. Use this for simple tag lists or keyword clouds.

```tsx live
<Tags>
  <Tag color="primary">Primary</Tag>
  <Tag color="info">Info</Tag>
  <Tag color="success">Success</Tag>
</Tags>
```

### Add-ons (Grouped)

Set the `hasAddons` prop to group tags together as add-ons, removing spacing between them for a compact, connected look.

```tsx live
<Tags hasAddons>
  <Tag color="primary">Package</Tag>
  <Tag color="success">Ready</Tag>
  <Tag isDelete onDelete={() => alert('Deleted!')} />
</Tags>
```

### Multiline

Use the `isMultiline` prop to allow tags to wrap onto multiple lines, making the tag group responsive for long lists.

```tsx live
<Tags isMultiline>
  <Tag color="primary">Bulma</Tag>
  <Tag color="success">React</Tag>
  <Tag color="warning">Typescript</Tag>
  <Tag color="danger">Library</Tag>
  <Tag color="link">UI</Tag>
</Tags>
```

### With Margin

You can use Bulma helper props like `m="4"` to add margin around the tag group for spacing within layouts.

```tsx live
<Tags m="4">
  <Tag color="primary">With Margin</Tag>
</Tags>
```

### Mixed Tags

Combine props such as `isMultiline`, `size`, `isRounded`, and `isDelete` to create flexible, interactive tag groups for advanced UIs.

```tsx live
function example() {
  const [show, setShow] = useState();

  return (
    <Tags isMultiline>
      <Tag color="primary" size="medium">
        Primary Medium
      </Tag>
      <Tag color="success" isRounded>
        Success Rounded
      </Tag>
      {/* Dismissible tag */}
      {show && <Tag color="danger" isDelete onDelete={() => setShow(false)} />}
      <Tag color="info">Info</Tag>
    </Tags>
  );
}
```

### Add-ons with Delete Tag

You can combine `hasAddons` with a delete tag to create a tightly grouped, dismissible tag set.

```tsx live
<Tags hasAddons>
  <Tag color="danger">Allxsmith</Tag>
  <Tag isDelete onDelete={() => alert('Deleted!')} />
</Tags>
```

---

## Accessibility

- **Grouping:** The container is a ``, which is semantically neutral.
- **Delete buttons:** If using delete tags, ensure each has an accessible label.
- **Multiline:** `isMultiline` ensures tags wrap for better readability on small screens.

:::tip
Use `hasAddons` for tightly grouped tags (no space between them).
:::

---

## Related Components

- [`Tag`](./tag.md): For individual tag elements.
- [`Delete`](./delete.md): For standalone delete buttons.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Tags Documentation](https://bulma.io/documentation/elements/tag/#list-of-tags)
- [Storybook: Tag Stories](https://bestax.io/storybook/?path=/story/elements-tag--default)

---

## Title


## Overview

The `Title` component renders a Bulma-styled title (heading), supporting sizes `1`-`6`, spacing, and rendering as any heading or paragraph element (`h1`-`h6`, `p`). Use it for section headings, page titles, and prominent text.

:::info
Pair `Title` with `SubTitle` for semantic and visually balanced headings.
:::

---

## Import

```tsx

```

---

## Props

| Prop          | Type                                                                                                                                                                                                                                                                                     | Default | Description                                              |
| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------- |
| `className`   | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                                  |
| `size`        | `'1' \| '2' \| '3' \| '4' \| '5' \| '6'`                                                                                                                                                                                                                                                 | —       | Size of the title (Bulma sizes).                         |
| `isSpaced`    | `boolean`                                                                                                                                                                                                                                                                                | —       | Adds margin below the title.                             |
| `as`          | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6' \| 'p'`                                                                                                                                                                                                                                    | `'h1'`  | HTML element to render as.                               |
| `hasSkeleton` | `boolean`                                                                                                                                                                                                                                                                                | —       | Applies the `has-skeleton` class to part of the content. |
| `skeleton`    | `boolean`                                                                                                                                                                                                                                                                                | —       | Applies the `is-skeleton` class to the entire component. |
| `children`    | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Title content.                                           |
| `textColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                                       |
| `bgColor`     | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                                 |
| ...           | All standard heading/paragraph and Bulma helper props                                                                                                                                                                                                                                    |         | (See [Helper Props](../helpers/usebulmaclasses))         |

---

## Usage

### Default Title

A basic `Title` renders a prominent heading. Use this for main section or page titles.

```tsx live
<Title>Default Title</Title>
```

### Has Skeleton

Set the `hasSkeleton` prop to apply a skeleton effect to part of the title, useful for partial loading states.

```tsx live
<Title hasSkeleton>Title with Skeleton Effect</Title>
```

`hasSkeleton` will only turn a small part of the content into a skeleton, typically for partial loading effects.

### Is Skeleton

Set the `skeleton` prop to apply a skeleton effect to the entire title, indicating that the whole heading is loading.

```tsx live
<Title skeleton>Title Skeleton Effect</Title>
```

`skeleton` applies the `is-skeleton` class to the entire title, making the whole heading appear as a skeleton placeholder.

### Different Sizes

Adjust the `size` prop to render the title in different Bulma-styled sizes, from `1` to `6`.

```tsx live
<>
  <Title size="1">Title Size 1</Title>
  <Title size="3">Title Size 3</Title>
</>
```

### Spaced Title

Use the `isSpaced` prop to add margin below the title, creating visual separation from other content.

```tsx live
<Title isSpaced>Spaced Title</Title>
```

### With Margin

Utilize margin helper props like `m="4"` to add custom margins around the title.

```tsx live
<Title m="4">Title with Margin</Title>
```

### As Paragraph

Render the title as a paragraph element by setting the `as` prop to `"p"`, while still applying heading styles.

```tsx live
<Title as="p" size="3">
  Title as Paragraph
</Title>
```

### All Sizes

Quickly render titles of all sizes from `1` to `6` using a map function. This is useful for demonstrating or testing all size variations.

```tsx live
<>
  {['1', '2', '3', '4', '5', '6'].map(size => (
    <Title key={size} size={size}>
      Title Size {size}
    </Title>
  ))}
</>
```

### Title and Subtitle

Combine `Title` with `SubTitle` for a structured heading and subheading layout. This is ideal for emphasizing the relationship between a title and its subtitle.

```tsx live
<Block>
  <Title as="p" size="1">
    Title 1
  </Title>
  <SubTitle as="p" size="3">
    Subtitle 3
  </SubTitle>
</Block>
```

---

## Accessibility

- **Semantic HTML:** Use appropriate heading levels for document structure.
- **Spacing:** Use `isSpaced` for extra margin when needed.
- **Screen readers:** Headings are key landmarks, so set the correct `as` and `size` prop for hierarchy.

:::tip
When using `as="p"`, the element is visually styled as a heading but semantically a paragraph.
:::

---

## Related Components

- [`SubTitle`](./subtitle.md): For secondary headings.
- [`Block`](./block.md): For spacing and grouping content.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [Bulma Title Documentation](https://bulma.io/documentation/elements/title/)
- [Storybook: Title Stories](https://bestax.io/storybook/?path=/story/elements-title--default)

---

## UnorderedList


## Overview

The `UnorderedList` component renders a styled unordered list (``) element with Bulma helper class integration. Use it with `ListItem` components to create bulleted lists with consistent styling.

:::info
The UnorderedList component is a thin wrapper around the HTML `` element, providing consistent Bulma styling and helper class support.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                               |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                         |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | List items to render inside the list.            |
| ...         | All standard `` and Bulma helper props                                                                                                                                                                                                                                               |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

:::info Wrap Lists in Content for Traditional Styling
Without a [`Content`](./content.md) wrapper, Bulma renders lists without the traditional margin, padding, and list-style markers (bullets, numbers). Wrap your lists in `<Content>` to get the expected typographic list appearance.
:::

### Default List

The default usage of the `UnorderedList` component with `ListItem` children.

```tsx live
<Content>
  <UnorderedList>
    <ListItem>First item</ListItem>
    <ListItem>Second item</ListItem>
    <ListItem>Third item</ListItem>
  </UnorderedList>
</Content>
```

### Colored List

Apply text color to all list items at once.

```tsx live
<Content>
  <UnorderedList textColor="primary">
    <ListItem>First item</ListItem>
    <ListItem>Second item</ListItem>
    <ListItem>Third item</ListItem>
  </UnorderedList>
</Content>
```

### List with Background

Add a background color and padding for a contained look.

```tsx live
<Content>
  <UnorderedList bgColor="dark" textColor="white" p="6">
    <ListItem>First item</ListItem>
    <ListItem>Second item</ListItem>
    <ListItem>Third item</ListItem>
  </UnorderedList>
</Content>
```

### Nested Lists

Create nested lists for hierarchical content.

```tsx live
<Content>
  <UnorderedList>
    <ListItem>First item</ListItem>
    <ListItem>
      Second item with nested list
      <UnorderedList>
        <ListItem>Nested item 1</ListItem>
        <ListItem>Nested item 2</ListItem>
      </UnorderedList>
    </ListItem>
    <ListItem>Third item</ListItem>
  </UnorderedList>
</Content>
```

### Individually Colored Items

Apply different colors to individual list items.

```tsx live
<Content>
  <UnorderedList>
    <ListItem textColor="primary">Primary item</ListItem>
    <ListItem textColor="success">Success item</ListItem>
    <ListItem textColor="warning">Warning item</ListItem>
    <ListItem textColor="danger">Danger item</ListItem>
  </UnorderedList>
</Content>
```

---

## Accessibility

- **List Structure:** Screen readers announce the list and the number of items, helping users understand the content structure.
- **Semantic Markup:** Using proper `` and `` elements ensures accessibility for all users.
- **Nesting:** Properly nested lists maintain correct semantics for assistive technologies.

:::info
Use `UnorderedList` when the order of items is not significant. For ordered content, use `OrderedList`.
:::

---

## Related Components

- [`OrderedList`](./orderedlist.md): For numbered/ordered lists.
- [`ListItem`](./listitem.md): Individual list item component.
- [`Content`](./content.md): For rich typographic content including lists.
- [Helper Props](../helpers/usebulmaclasses.md): Bulma helper props for spacing, color, etc.

---

## Additional Resources

- [MDN: ul element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul)
- [Storybook: UnorderedList Stories](https://bestax.io/storybook/?path=/story/elements-unorderedlist--default)

---

## Autocomplete


## Overview

The `Autocomplete` component provides an input field with dropdown suggestions that filter based on user input. It supports both string arrays and object data, keyboard navigation, and custom templates.

---

## Import

```tsx

```

---

## Props

| Prop                     | Type                                                                            | Default   | Description                                                       |
| ------------------------ | ------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------- |
| `data`                   | `AutocompleteItem[]` \| `string[]`                                              | —         | The options data to display (required).                           |
| `value`                  | `string`                                                                        | —         | The current input value (controlled).                             |
| `selected`               | `AutocompleteItem` \| `string` \| `null`                                        | —         | The selected item (controlled).                                   |
| `placeholder`            | `string`                                                                        | —         | Placeholder text for the input.                                   |
| `field`                  | `string`                                                                        | `'label'` | Object property to use as the display field.                      |
| `clearable`              | `boolean`                                                                       | `false`   | Whether to show a clear button.                                   |
| `openOnFocus`            | `boolean`                                                                       | `false`   | Open dropdown when input is focused.                              |
| `keepFirst`              | `boolean`                                                                       | `false`   | Keep first option highlighted.                                    |
| `keepOpen`               | `boolean`                                                                       | `false`   | Keep dropdown open after selection.                               |
| `selectOnClickOutside`   | `boolean`                                                                       | `false`   | Select highlighted item on click outside.                         |
| `maxHeight`              | `number`                                                                        | `200`     | Maximum dropdown height in pixels.                                |
| `dropdown`               | `boolean`                                                                       | `false`   | Render as dropdown style.                                         |
| `loading`                | `boolean`                                                                       | `false`   | Show loading state.                                               |
| `disabled`               | `boolean`                                                                       | `false`   | Whether the input is disabled.                                    |
| `color`                  | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` | —         | Input color variant.                                              |
| `size`                   | `'small'` \| `'medium'` \| `'large'`                                            | —         | Size variant.                                                     |
| `onInput`                | `(value: string) => void`                                                       | —         | Callback when input value changes.                                |
| `onSelect`               | `(item: AutocompleteItem \| string \| null) => void`                            | —         | Callback when item is selected.                                   |
| `onActiveChange`         | `(active: boolean) => void`                                                     | —         | Callback when dropdown active state changes.                      |
| `onInfiniteScroll`       | `() => void`                                                                    | —         | Callback when scrolled to bottom.                                 |
| `checkInfiniteScroll`    | `boolean`                                                                       | `false`   | Enables infinite scroll detection in the dropdown.                |
| `infiniteScrollDistance` | `number`                                                                        | `50`      | Distance in pixels from the bottom to trigger `onInfiniteScroll`. |
| `itemTemplate`           | `(item: AutocompleteItem \| string) => React.ReactNode`                         | —         | Custom render for items.                                          |
| `header`                 | `React.ReactNode`                                                               | —         | Custom header in dropdown.                                        |
| `footer`                 | `React.ReactNode`                                                               | —         | Custom footer in dropdown.                                        |
| `empty`                  | `React.ReactNode`                                                               | —         | Content to show when no results.                                  |
| `className`              | `string`                                                                        | —         | Additional CSS classes.                                           |
| `ref`                    | `React.Ref<HTMLElement>`                                                        | —         | Ref forwarded to the input element.                               |
| ...                      | All standard HTML and Bulma helper props                                        |           | (See [Helper Props](../helpers/usebulmaclasses))                  |

### AutocompleteItem

| Prop       | Type      | Description               |
| ---------- | --------- | ------------------------- |
| `value`    | `string`  | The item value.           |
| `label`    | `string`  | Display label (optional). |
| `disabled` | `boolean` | Whether item is disabled. |

---

## Usage

### Basic Autocomplete

Simple autocomplete with string array.

```tsx live
function example() {
  const [selected, setSelected] = useState(null);
  const fruits = [
    'Apple',
    'Banana',
    'Cherry',
    'Date',
    'Elderberry',
    'Fig',
    'Grape',
  ];

  return (
    <Block>
      <Autocomplete
        data={fruits}
        placeholder="Search fruit..."
        onSelect={setSelected}
      />
      {selected && <Paragraph mt="2">Selected: {selected}</Paragraph>}
    </Block>
  );
}
```

---

### Open on Focus

Dropdown opens immediately when input is focused.

```tsx live
function example() {
  const [selected, setSelected] = useState(null);
  const countries = [
    'United States',
    'United Kingdom',
    'Canada',
    'Australia',
    'Germany',
    'France',
  ];

  return (
    <Autocomplete
      data={countries}
      placeholder="Select a country..."
      openOnFocus
      onSelect={setSelected}
    />
  );
}
```

---

### With Clear Button

Autocomplete with clearable input.

```tsx live
function example() {
  const [selected, setSelected] = useState(null);
  const options = ['Option 1', 'Option 2', 'Option 3', 'Option 4'];

  return (
    <Autocomplete
      data={options}
      placeholder="Search options..."
      clearable
      onSelect={setSelected}
    />
  );
}
```

---

### Color and Size Variants

Autocomplete with different colors and sizes.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <Autocomplete
    data={['Apple', 'Banana', 'Cherry']}
    placeholder="Primary small"
    color="primary"
    size="small"
  />
  <Autocomplete
    data={['Apple', 'Banana', 'Cherry']}
    placeholder="Info normal"
    color="info"
  />
  <Autocomplete
    data={['Apple', 'Banana', 'Cherry']}
    placeholder="Success medium"
    color="success"
    size="medium"
  />
  <Autocomplete
    data={['Apple', 'Banana', 'Cherry']}
    placeholder="Danger large"
    color="danger"
    size="large"
  />
</Block>
```

---

### With Object Data

Autocomplete with object items.

```tsx live
function example() {
  const [selected, setSelected] = useState(null);
  const users = [
    { value: '1', label: 'John Doe', email: 'john@example.com' },
    { value: '2', label: 'Jane Smith', email: 'jane@example.com' },
    { value: '3', label: 'Bob Johnson', email: 'bob@example.com' },
  ];

  return (
    <Block>
      <Autocomplete
        data={users}
        field="label"
        placeholder="Search users..."
        openOnFocus
        onSelect={setSelected}
      />
      {selected && (
        <Paragraph mt="2">
          Selected: {selected.label} ({selected.email})
        </Paragraph>
      )}
    </Block>
  );
}
```

---

### Custom Item Template

Autocomplete with custom item rendering.

```tsx live
function example() {
  const [selected, setSelected] = useState(null);
  const users = [
    { value: '1', label: 'John Doe', role: 'Admin' },
    { value: '2', label: 'Jane Smith', role: 'Editor' },
    { value: '3', label: 'Bob Johnson', role: 'Viewer' },
  ];

  return (
    <Autocomplete
      data={users}
      field="label"
      placeholder="Search users..."
      openOnFocus
      onSelect={setSelected}
      itemTemplate={item => (
        <Block display="flex" justifyContent="space-between">
          {item.label}
          <Tag color="info" light>
            {item.role}
          </Tag>
        </Block>
      )}
    />
  );
}
```

---

### With Empty State

Custom content when no results match.

```tsx live
function example() {
  const options = ['Apple', 'Banana', 'Cherry'];

  return (
    <Autocomplete
      data={options}
      placeholder="Try searching 'xyz'..."
      empty={
        <Paragraph textColor="grey">
          <Icon name="search" variant="solid" mr="2" />
          No results found
        </Paragraph>
      }
    />
  );
}
```

---

### Loading State

Autocomplete showing loading indicator.

```tsx live
<Autocomplete data={[]} placeholder="Loading..." loading />
```

---

### Keep First Highlighted

First option stays highlighted while typing.

```tsx live
function example() {
  const fruits = [
    'Apple',
    'Apricot',
    'Avocado',
    'Banana',
    'Blackberry',
    'Blueberry',
  ];

  return (
    <Autocomplete data={fruits} placeholder="Type to filter..." keepFirst />
  );
}
```

---

### Context-Aware Rendering

The `Autocomplete` component is context-aware: it detects whether it is already inside a `Field` and adjusts its rendering accordingly. This means you can use it standalone with a `label` prop (it wraps itself in a Field), or inside a `Field` (it skips rendering its own).

:::note
Autocomplete does not use ControlContext, so the "With Field and Control Wrappers" example below uses Field wrapping only. The Control wrapper is shown for layout consistency but does not change the component's internal rendering.
:::

#### Default (with label)

The simplest usage — the component automatically renders its own Field wrapper.

```tsx live
<Autocomplete
  label="Fruit"
  data={['Apple', 'Banana', 'Cherry']}
  placeholder="Search fruit..."
/>
```

---

#### With Field Wrapper

When you need manual control over the Field layout (e.g., horizontal forms), wrap the component in `Field`. The component detects it's inside a Field and skips rendering its own.

```tsx live
function example() {
  return (
    <Field horizontal label="Fruit">
      <Field.Body>
        <Field>
          <Autocomplete
            data={['Apple', 'Banana', 'Cherry']}
            placeholder="Search fruit..."
          />
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

For full manual composition with icons, wrap in both Field and Control. Autocomplete does not consume ControlContext, but the Field wrapper is still detected and its own Field is skipped.

```tsx live
function example() {
  return (
    <Field horizontal label="Fruit">
      <Field.Body>
        <Field>
          <Control iconLeftName="search">
            <Autocomplete
              data={['Apple', 'Banana', 'Cherry']}
              placeholder="Search fruit..."
            />
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

## Keyboard Navigation

| Key      | Action                            |
| -------- | --------------------------------- |
| `↓`      | Open dropdown / Move down         |
| `↑`      | Move up                           |
| `Enter`  | Select highlighted item           |
| `Tab`    | Select highlighted and move focus |
| `Escape` | Close dropdown                    |

---

## Form Submission

`Autocomplete` is an HTML form element. Pass a `name` prop and the typed/selected text is forwarded to the inner `<input>` so the value submits with the surrounding form, exactly like a native text input.

| Prop       | Description                                                  |
| ---------- | ------------------------------------------------------------ |
| `name`     | Form field name. Forwarded to the inner `<input>`.           |
| `form`     | Optional id of the form the input belongs to.                |
| `required` | Marks the field as required for native HTML form validation. |

```tsx live
function AutocompleteFormDemo() {
  const [submitted, setSubmitted] = React.useState('');
  return (
    <form
      onSubmit={e => {
        e.preventDefault();
        const fd = new FormData(e.currentTarget);
        setSubmitted(JSON.stringify(Array.from(fd.entries()), null, 2));
      }}
    >
      <Autocomplete
        name="city"
        data={['New York', 'London', 'Paris', 'Tokyo', 'Sydney']}
        placeholder="Search a city…"
      />
      
        <button type="submit" className="button is-primary">
          Submit
        </button>
      
      {submitted && <pre style={{ marginTop: '1rem' }}>{submitted}</pre>}
    </form>
  );
}
```

---

## Accessibility

- Uses `role="combobox"` with `aria-expanded`
- Has `aria-haspopup="listbox"` and `aria-autocomplete="list"`
- Dropdown items use `role="option"` with `aria-selected`
- Disabled items have `aria-disabled`
- Full keyboard navigation support

---

## Related Components

- [Taginput](./taginput.md) - For multiple tag selection with autocomplete
- [Select](./select.md) - For simple dropdown selection
- [Input](./input.md) - For basic text input

---

## Additional Resources

- [Storybook: Autocomplete Stories](https://bestax.io/storybook/?path=/story/form-autocomplete)

:::tip Pro Tip
Use `keepFirst` combined with `Enter` to quickly select the first matching result without using the mouse.
:::

---

## Checkbox


## Overview

The `Checkbox` component provides a Bulma-styled checkbox input. Pass the label as children; you can include plain text, links, or custom JSX. Use it for boolean choices and combine with the `Checkboxes` component for grouped options.

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `disabled`  | `boolean`                                                                                                                                                                                                                                                                                | Whether the checkbox is disabled.                |
| `color`     | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`                                                                                                                                                                                                          | Color of the checkbox.                           |
| `size`      | `'small'` \| `'normal'` \| `'medium'` \| `'large'`                                                                                                                                                                                                                                       | Size of the checkbox.                            |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | Text color helper.                               |
| `className` | `string`                                                                                                                                                                                                                                                                                 | Additional CSS classes.                          |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | Label/content for the checkbox.                  |
| ...         | All standard `<input>` and Bulma helper props                                                                                                                                                                                                                                            | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Basic Checkbox

This example shows a simple `Checkbox` component for a single boolean choice. The label is provided as the `children` prop, and the checkbox is fully accessible and styled with Bulma.

```tsx live
<Checkbox> Stay Signed In </Checkbox>
```

### Checkbox With Link

This example demonstrates using the `Checkbox` component with a custom label that includes a link. The `children` prop can contain any React nodes, such as anchor tags, to create rich, accessible labels for agreements or terms.

```tsx live
<Checkbox>
  I have read and agree to the
  
    terms and conditions
  
  .
</Checkbox>
```

### Disabled Checkbox

Set the `disabled` prop to render a non-interactive checkbox. This is useful for indicating unavailable options in forms, and the checkbox will appear visually disabled and cannot be toggled by the user.

```tsx live
<Checkbox disabled> Stay Signed In </Checkbox>
```

### Group/List of Checkboxes

This example uses the `Checkboxes` component to render a list of checkboxes. Each `Checkbox` receives its own label via the `children` prop. Use this pattern for lists of boolean options, such as tasks or preferences.

```tsx live
<Checkboxes>
  <Checkbox> Make the bed </Checkbox>
  <Checkbox> Brush teeth </Checkbox>
  <Checkbox> Do homework </Checkbox>
  <Checkbox> Feed the pet </Checkbox>
  <Checkbox> Take out the trash </Checkbox>
  <Checkbox> Clean your room </Checkbox>
  <Checkbox> Set the table </Checkbox>
  <Checkbox> Help with dishes </Checkbox>
  <Checkbox> Water the plants </Checkbox>
  <Checkbox> Put away toys </Checkbox>
</Checkboxes>
```

---

## Accessibility

- Each `Checkbox` is rendered as a `<label>` wrapping an `<input type="checkbox">` and the label text, for optimal accessibility.
- The clickable area includes both box and label by default.

---

## Related Components

- [`Checkboxes`](./checkboxes.md) – for grouped checkboxes.
- [`Field`](./field.md) – for labeled/structured forms.
- [Helper Props](../helpers/usebulmaclasses.md)

---

## Additional Resources

- [Bulma Checkbox Documentation](https://bulma.io/documentation/form/checkbox/)
- [Storybook: Checkbox Stories](https://bestax.io/storybook/?path=/story/form-checkbox--default)

---

## Related Components

- [`Checkboxes`](./checkboxes.md): For grouped checkboxes.
- [`Field`](./field.md): For forms.
- [Helper Props](../helpers/usebulmaclasses.md): For spacing, color, etc.

---

## Additional Resources

- [Bulma Checkbox Documentation](https://bulma.io/documentation/form/checkbox/)
- [Storybook: Checkbox Stories](https://bestax.io/storybook/?path=/story/form-checkbox--default)

---

## Checkboxes


## Overview

The `Checkboxes` component wraps multiple `Checkbox` components in a Bulma-styled group. Use for lists of boolean choices, such as preference lists or to-do checklists.

---

## Import

```tsx

```

---

## Props

| Prop           | Type                         | Description                                                          |
| -------------- | ---------------------------- | -------------------------------------------------------------------- |
| `name`         | `string`                     | Form field name shared by every Checkbox in the group (via context). |
| `value`        | `string[]`                   | Currently-selected values (controlled mode).                         |
| `defaultValue` | `string[]`                   | Initial selected values (uncontrolled mode).                         |
| `onChange`     | `(values: string[]) => void` | Fires when the selection changes; receives the new array.            |
| `className`    | `string`                     | Additional CSS classes.                                              |
| `children`     | `React.ReactNode`            | Checkbox elements to render in the group.                            |
| ...            | All Bulma helper props       | (See [Helper Props](../helpers/usebulmaclasses))                     |

---

## Usage

### Grouped Checkboxes

This example demonstrates the `Checkboxes` component wrapping multiple `Checkbox` children. Use this pattern for lists of boolean options, such as to-do lists or preference selections. Each `Checkbox` receives its own label via the `children` prop.

```tsx live
<Checkboxes>
  <Checkbox> Make the bed </Checkbox>
  <Checkbox> Brush teeth </Checkbox>
  <Checkbox> Do homework </Checkbox>
  <Checkbox> Feed the pet </Checkbox>
  <Checkbox> Take out the trash </Checkbox>
  <Checkbox> Clean your room </Checkbox>
  <Checkbox> Set the table </Checkbox>
  <Checkbox> Help with dishes </Checkbox>
  <Checkbox> Water the plants </Checkbox>
  <Checkbox> Put away toys </Checkbox>
</Checkboxes>
```

---

### Context-Aware Rendering

The `Checkboxes` component is context-aware: it detects whether it is already inside a `Field` or `Control` and adjusts its rendering accordingly. This means you can use it standalone with a `label` prop (it wraps itself in Field+Control), inside a `Field` (it skips its own Field), or inside both `Field` and `Control` (it renders only the raw checkbox group).

#### Default (with label)

The simplest usage — the component automatically renders its own Field and Control wrappers.

```tsx live
<Checkboxes label="Chores">
  <Checkbox> Make the bed </Checkbox>
  <Checkbox> Brush teeth </Checkbox>
  <Checkbox> Do homework </Checkbox>
</Checkboxes>
```

---

#### With Field Wrapper

When you need manual control over the Field layout (e.g., horizontal forms), wrap the component in `Field`. The component detects it's inside a Field and skips rendering its own.

```tsx live
function example() {
  return (
    <Field horizontal label="Chores">
      <Field.Body>
        <Field>
          <Checkboxes>
            <Checkbox> Make the bed </Checkbox>
            <Checkbox> Brush teeth </Checkbox>
            <Checkbox> Do homework </Checkbox>
          </Checkboxes>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

For full manual control, wrap in both Field and Control. The component detects both and renders only the raw checkbox group.

```tsx live
function example() {
  return (
    <Field horizontal label="Chores">
      <Field.Body>
        <Field>
          <Control>
            <Checkboxes>
              <Checkbox> Make the bed </Checkbox>
              <Checkbox> Brush teeth </Checkbox>
              <Checkbox> Do homework </Checkbox>
            </Checkboxes>
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

## Group State

`Checkboxes` can manage the selected-values array for the entire group, matching the pattern used by React Aria's `CheckboxGroup`. Three usage modes:

1. **Name-only** — pass just `name`. Each child `Checkbox` manages its own checked state. Backwards compatible.
2. **Controlled** — pass `value` (an array of selected values) and `onChange`. The parent owns selection; each `Checkbox` derives `checked` from `value.includes(my.value)`.
3. **Uncontrolled** — pass `defaultValue` (an array) and optionally `onChange`. The group manages internal state; `onChange` fires with the new array.

Local props (`checked`, `onChange`) on individual `Checkbox` children always win over the group context.

### Controlled

```tsx live
function ControlledCheckboxes() {
  const [tags, setTags] = React.useState(['react']);
  return (
    
      <Checkboxes name="tags" value={tags} onChange={setTags}>
        <Checkbox value="react">React</Checkbox>
        <Checkbox value="vue">Vue</Checkbox>
        <Checkbox value="angular">Angular</Checkbox>
        <Checkbox value="svelte">Svelte</Checkbox>
      </Checkboxes>
      
        Selected: {tags.length ? tags.join(', ') : '(none)'}
      
    
  );
}
```

### Uncontrolled

```tsx live
function UncontrolledCheckboxes() {
  const [latest, setLatest] = React.useState([]);
  return (
    
      <Checkboxes
        name="features"
        defaultValue={['darkmode']}
        onChange={setLatest}
      >
        <Checkbox value="darkmode">Dark mode</Checkbox>
        <Checkbox value="notifications">Notifications</Checkbox>
        <Checkbox value="analytics">Analytics</Checkbox>
      </Checkboxes>
      {latest.length > 0 && (
        
          Latest: {latest.join(', ')}
        
      )}
    
  );
}
```

---

## Form Submission

`Checkboxes` is HTML-form-compatible. Pass a `name` prop on the group and every child `Checkbox` inherits it via React context (works at any nesting depth). Each checked box submits as `name=value`, producing a standard form-encoded array (e.g., `tags=react&tags=vue`) that server-side parsers handle natively.

| Prop   | Description                                                                                                            |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `name` | Form field name shared by every child Checkbox. Children with their own `name` prop keep theirs (explicit > implicit). |

```tsx live
function CheckboxesFormDemo() {
  const [submitted, setSubmitted] = React.useState('');
  return (
    <form
      onSubmit={e => {
        e.preventDefault();
        const fd = new FormData(e.currentTarget);
        setSubmitted(JSON.stringify(Array.from(fd.entries()), null, 2));
      }}
    >
      <Checkboxes name="tags">
        <Checkbox value="react" defaultChecked>
          React
        </Checkbox>
        <Checkbox value="vue" defaultChecked>
          Vue
        </Checkbox>
        <Checkbox value="angular">Angular</Checkbox>
        <Checkbox value="svelte">Svelte</Checkbox>
      </Checkboxes>
      
        <button type="submit" className="button is-primary">
          Submit
        </button>
      
      {submitted && <pre style={{ marginTop: '1rem' }}>{submitted}</pre>}
    </form>
  );
}
```

---

## Accessibility

- The group is rendered as a `` containing labeled checkboxes.
- Each child should be a `Checkbox` for proper labeling and accessibility.

---

## Related Components

- [`Checkbox`](./checkbox.md): Individual checkbox.
- [`Field`](./field.md): For labeled/grouped form fields.

---

## Additional Resources

- [Bulma Checkboxes Documentation](https://bulma.io/documentation/form/checkbox/#grouped-checkboxes)
- [Storybook: Checkbox Stories](https://bestax.io/storybook/?path=/story/form-checkbox--listofcheckboxes)

---

## Control


## Overview

The `Control` component is a Bulma-styled wrapper for form controls (`Input`, `Select`, `TextArea`, etc.), supporting icons (left/right), loading state, expansion, size, and Bulma helper props for layout and color. Use it to provide consistent spacing, icon placement, and loading indicators for any form element.

---

## Import

```tsx

// ...and other form elements as needed
```

---

## Props

| Prop            | Type                                                                  | Description                                                                         |
| --------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `hasIconsLeft`  | `boolean`                                                             | Adds left icon container.                                                           |
| `hasIconsRight` | `boolean`                                                             | Adds right icon container.                                                          |
| `isLoading`     | `boolean`                                                             | Shows loading indicator.                                                            |
| `isExpanded`    | `boolean`                                                             | Makes the control expand to fill available space.                                   |
| `size`          | `'small' \| 'medium' \| 'large'`                                      | Sets the control size.                                                              |
| `textColor`     | [Bulma color]\*, `'inherit'`, `'current'`                             | Sets text color.                                                                    |
| `color`         | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'` | Bulma color for the control.                                                        |
| `bgColor`       | [Bulma color]\*, `'inherit'`, `'current'`                             | Background color.                                                                   |
| `iconLeft`      | `IconProps`                                                           | Icon props for left icon.                                                           |
| `iconRight`     | `IconProps`                                                           | Icon props for right icon.                                                          |
| `iconLeftName`  | `string`                                                              | Shortcut for left icon name.                                                        |
| `iconLeftSize`  | `'small' \| 'medium' \| 'large'`                                      | Shortcut for left icon size.                                                        |
| `iconRightName` | `string`                                                              | Shortcut for right icon name.                                                       |
| `iconRightSize` | `'small' \| 'medium' \| 'large'`                                      | Shortcut for right icon size.                                                       |
| `className`     | `string`                                                              | Additional CSS classes to apply.                                                    |
| `children`      | `React.ReactNode`                                                     | Content inside the control.                                                         |
| `as`            | `'div' \| 'p'`                                                        | Element type for the control (`div` by default).                                    |
| `ref`           | `React.Ref<HTMLDivElement \| HTMLParagraphElement>`                   | Ref for the control element.                                                        |
| ...             | All standard HTML and Bulma helper props                              | See [Helper Props](../helpers/usebulmaclasses.md) for available Bulma helper props. |

\* [Bulma color] options include: `'primary'`, `'link'`, `'info'`, `'success'`, `'warning'`, `'danger'`, `'black'`, `'black-bis'`, `'black-ter'`, `'grey-darker'`, `'grey-dark'`, `'grey'`, `'grey-light'`, `'grey-lighter'`, `'white'`, `'white-bis'`, `'white-ter'`.

---

## Usage

### With Input

This example shows the `Control` component wrapping an `Input` inside a `Field`. Use `Control` to provide consistent spacing and icon placement for form elements. The `placeholder` prop on `Input` provides hint text.

```tsx live
<Field label="Default">
  <Control>
    <Input placeholder="Default input" />
  </Control>
</Field>
```

---

### With Select

This example demonstrates using the `Control` component to wrap a `Select` element. The `Control` ensures proper Bulma styling and layout for the select dropdown.

```tsx live
<Field label="Default">
  <Control>
    <Select>
      <option value="">Please select</option>
      <option value="option1">Option 1</option>
      <option value="option2">Option 2</option>
    </Select>
  </Control>
</Field>
```

---

### With TextArea

This example shows a `Control` wrapping a `TextArea`. The `Control` component provides a styled container that can include icons, loading indicators, and size variations.

```tsx live
<Field label="Default">
  <Control>
    <TextArea placeholder="Write here..." />
  </Control>
</Field>
```

---

### With Icons (Left and Right)

This example demonstrates using the `Control` component with icons on both sides. The `hasIconsLeft` and `hasIconsRight` props add icon containers, and the `iconLeft` and `iconRight` props define the icons to be used.

```tsx live
<Field>
  <Control
    hasIconsLeft
    hasIconsRight
    iconLeft={{ name: 'user' }}
    iconRight={{ name: 'check' }}
  >
    <Input placeholder="With icons" />
  </Control>
</Field>
```

---

### With Only Left Icon (Shortcut Props)

This example shows how to use shortcut props for quickly adding an icon to the left of the input. The `iconLeftName` and `iconLeftSize` props are used for specifying the icon's name and size, respectively.

```tsx live
<Field>
  <Control hasIconsLeft iconLeftName="user" iconLeftSize="small">
    <Input size="small" placeholder="With left icon shortcut" />
  </Control>
</Field>
```

---

### With Only Right Icon (Shortcut Props)

Similar to the previous example, this one demonstrates adding an icon to the right of the input using shortcut props. The `iconRightName` and `iconRightSize` props define the icon's characteristics.

```tsx live
<Field>
  <Control hasIconsRight iconRightName="check" iconRightSize="small">
    <Input size="small" placeholder="With right icon shortcut" />
  </Control>
</Field>
```

---

### With Icons and Size Variations

This example combines icon usage with size variations. The `size` prop on `Control` and `Input` adjusts the size, while the `iconLeft` and `iconRight` props with size specifications control the icon sizes.

```tsx live
<Field>
  <Control
    hasIconsLeft
    hasIconsRight
    size="medium"
    iconLeft={{ name: 'user', size: 'medium' }}
    iconRight={{ name: 'check', size: 'medium' }}
  >
    <Input size="medium" placeholder="Icons left/right medium" />
  </Control>
</Field>
```

---

### Loading State

The `isLoading` prop can be used to indicate a loading state for the control. This example shows a control with an input field in a loading state.

```tsx live
<Field label="Loading">
  <Control isLoading>
    <Input placeholder="Loading state" />
  </Control>
</Field>
```

---

### Loading State with Size Variations

This example demonstrates the loading state with different size variations. The `size` prop is used to control the size of the `Control` and `Input` components.

```tsx live
<>
  <Field label="Loading Small">
    <Control isLoading size="small">
      <Input size="small" placeholder="Loading small" />
    </Control>
  </Field>

  <Field label="Loading Medium">
    <Control isLoading size="medium">
      <Input size="medium" placeholder="Loading medium" />
    </Control>
  </Field>

  <Field label="Loading Large">
    <Control isLoading size="large">
      <Input size="large" placeholder="Loading large" />
    </Control>
  </Field>
</>
```

---

### Expanded Control

The `isExpanded` prop makes the control expand to fill the available space. This example shows an expanded control with an input field.

```tsx live
<Field label="Expanded">
  <Control isExpanded>
    <Input placeholder="Expands to fill available space" />
  </Control>
</Field>
```

---

### Control as Paragraph (`as="p"`)

The `as` prop allows rendering the control as a different HTML element. This example shows the control rendered as a paragraph (``), which can be useful for inline forms or specific layout requirements.

```tsx live
<Field label="Control as Paragraph">
  <Control as="p">
    <Input placeholder="Inside a  element" />
  </Control>
</Field>
```

---

### With Radios or Checkboxes

The `Control` component can also be used with radio buttons or checkboxes. This example shows how to group radio buttons and checkboxes within a control.

```tsx live
<>
  <Field label="Options">
    <Control>
      <Radio name="option">Option 1</Radio>
      <Radio name="option">Option 2</Radio>
    </Control>
  </Field>

  <Field label="Preferences">
    <Control>
      <Checkbox>Enable notifications</Checkbox>
      <Checkbox>Subscribe to newsletter</Checkbox>
    </Control>
  </Field>
</>
```

---

## Accessibility

- `Control` provides only visual and layout structure; ensure you use associated `Field` and `label` for accessible form labeling.
- Icons are decorative by default. Add ARIA attributes to icons if needed for accessibility.

---

## Related Components

- [`Field`](./field.md): Use for labeling and grouping.
- [`Input`](./input.md), [`Select`](./select.md), [`TextArea`](./textarea.md), [`Radio`](./radio.md), [`Checkbox`](./checkbox.md): Use as children of `Control`.
- [Helper Props](../helpers/usebulmaclasses.md)

---

## Additional Resources

- [Bulma Control Documentation](https://bulma.io/documentation/form/general/#control)
- [Storybook: Input Stories](https://bestax.io/storybook/?path=/story/form-input--default)

---

## DateInput


## Overview

The `DateInput` component is a form input that opens a popover calendar for date selection. A clickable launcher icon on the right opens the popover, and you can type directly in the field with segmented keyboard entry. It uses native `Date` and `Intl` only (no extra dependencies), supports min/max bounds, disabled-date predicates, custom token formats or `Intl.DateTimeFormatOptions`, locale-aware day/month names, an inline mode, and a native `<input type="date">` fallback for touch devices.

---

## Import

```tsx

```

---

## Props

| Prop                | Type                                                                     | Default          | Description                                                                                                                                 |
| ------------------- | ------------------------------------------------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`             | `Date \| null`                                                           | —                | Controlled selected date.                                                                                                                   |
| `defaultValue`      | `Date \| null`                                                           | —                | Initial date for uncontrolled usage.                                                                                                        |
| `onChange`          | `(d: Date \| null) => void`                                              | —                | Fired when the value changes.                                                                                                               |
| `onOpen`            | `() => void`                                                             | —                | Fired when the popover opens.                                                                                                               |
| `onClose`           | `() => void`                                                             | —                | Fired when the popover closes.                                                                                                              |
| `min`               | `Date`                                                                   | —                | Earliest selectable date.                                                                                                                   |
| `max`               | `Date`                                                                   | —                | Latest selectable date.                                                                                                                     |
| `shouldDisableDate` | `(d: Date) => boolean`                                                   | —                | Predicate to disable specific dates (e.g. weekends). Blocked dates are also rejected during manual typing.                                  |
| `unselectableDates` | `Date[]`                                                                 | —                | Convenience array of disabled dates; merged with `shouldDisableDate`. Matched by calendar day and also rejected during manual typing.       |
| `firstDayOfWeek`    | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`                                        | `0`              | Day the week starts on (0 = Sunday).                                                                                                        |
| `dayNames`          | `string[]`                                                               | —                | Override the 7 day-name labels (in calendar order, post-rotation).                                                                          |
| `monthNames`        | `string[]`                                                               | —                | Override the 12 month-name labels.                                                                                                          |
| `nearbyMonthDays`   | `boolean`                                                                | `true`           | Show dimmed dates from adjacent months in the grid.                                                                                         |
| `placeholder`       | `string`                                                                 | —                | Placeholder text for the input.                                                                                                             |
| `format`            | `string \| Intl.DateTimeFormatOptions`                                   | `'YYYY-MM-DD'`   | Token format string or `Intl.DateTimeFormat` options.                                                                                       |
| `parse`             | `(s: string) => Date \| null`                                            | —                | Custom parser (use when `format` is `Intl.DateTimeFormatOptions`).                                                                          |
| `locale`            | `string`                                                                 | —                | BCP-47 locale tag for day/month names and Intl formatting.                                                                                  |
| `inline`            | `boolean`                                                                | `false`          | Render the calendar inline (no popover).                                                                                                    |
| `mobileNative`      | `boolean \| 'auto'`                                                      | `'auto'`         | Use `<input type="date">` on coarse-pointer + small-viewport devices.                                                                       |
| `editable`          | `boolean`                                                                | `true`           | Allow segmented keyboard typing in the input (type the date directly, auto-advancing across segments). `false` makes the field picker-only. |
| `popover`           | `boolean`                                                                | `true`           | Whether the calendar popover exists. `false` makes the field input-only (segmented typing, no popover).                                     |
| `openOnFocus`       | `boolean`                                                                | `true`           | Open the popover when the input is focused.                                                                                                 |
| `closeOnSelect`     | `boolean`                                                                | `true`           | Close the popover after a date is selected.                                                                                                 |
| `position`          | `'bottom-left' \| 'bottom-right' \| 'top-left' \| 'top-right' \| 'auto'` | `'bottom-left'`  | Popover anchor position relative to the input.                                                                                              |
| `appendToBody`      | `boolean`                                                                | `false`          | Render the popover into `document.body` via portal.                                                                                         |
| `disabled`          | `boolean`                                                                | `false`          | Disable the input.                                                                                                                          |
| `readOnly`          | `boolean`                                                                | `false`          | Make the input read-only.                                                                                                                   |
| `color`             | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`    | —                | Bulma color modifier.                                                                                                                       |
| `size`              | `'small' \| 'medium' \| 'large'`                                         | —                | Size variant.                                                                                                                               |
| `isRounded`         | `boolean`                                                                | `false`          | Render the input with rounded corners.                                                                                                      |
| `iconLeftName`      | `string`                                                                 | `'calendar'`     | Decorative left icon glyph for the wrapping `Control` (shown by default). Set `''` to hide.                                                 |
| `triggerIcon`       | `boolean`                                                                | `true`           | Show a clickable launcher button on the right that toggles the popover.                                                                     |
| `triggerIconName`   | `string`                                                                 | `'chevron-down'` | Glyph for the right launcher button.                                                                                                        |
| `name`              | `string`                                                                 | —                | Form field name. Forwarded to a hidden ISO-formatted input.                                                                                 |
| `form`              | `string`                                                                 | —                | Form id the input belongs to.                                                                                                               |
| `required`          | `boolean`                                                                | `false`          | Marks the input as required.                                                                                                                |
| `label`             | `React.ReactNode`                                                        | —                | Field label (component auto-wraps in a `Field` if not already inside).                                                                      |
| `horizontal`        | `boolean`                                                                | `false`          | Render the field with horizontal layout.                                                                                                    |
| `message`           | `React.ReactNode`                                                        | —                | Help/validation text below the input.                                                                                                       |
| `messageColor`      | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`    | —                | Color modifier for the help message.                                                                                                        |
| `className`         | `string`                                                                 | —                | Additional CSS classes for the input.                                                                                                       |
| `ref`               | `React.Ref<HTMLInputElement>`                                            | —                | Forwarded to the underlying `<input>`.                                                                                                      |
| ...                 | All standard HTML and Bulma helper props                                 |                  | (See [Helper Props](../../helpers/usebulmaclasses))                                                                                         |

---

## Usage

### Basic DateInput

A simple date picker with a popover calendar.

```tsx live
function example() {
  return <DateInput label="Pick a date" placeholder="YYYY-MM-DD" />;
}
```

**Typing-first** — the same example with `openOnFocus={false}`: focusing or clicking the field lets you type; open the popover with the launcher icon (or press `↓`).

```tsx live
function example() {
  return (
    <DateInput
      label="Type a date"
      placeholder="YYYY-MM-DD"
      openOnFocus={false}
    />
  );
}
```

---

### Controlled

Manage state externally with `value` and `onChange`.

```tsx live
function example() {
  const [value, setValue] = useState(new Date());
  return (
    <Block>
      <DateInput label="Date" value={value} onChange={setValue} />
      <Paragraph mt="2">
        Selected: {value ? value.toDateString() : '—'}
      </Paragraph>
    </Block>
  );
}
```

**Typing-first** — identical, but with `openOnFocus={false}` so focusing just lets you type; the calendar waits behind the launcher icon (or `↓`).

```tsx live
function example() {
  const [value, setValue] = useState(new Date());
  return (
    <Block>
      <DateInput
        label="Date"
        value={value}
        onChange={setValue}
        openOnFocus={false}
      />
      <Paragraph mt="2">
        Selected: {value ? value.toDateString() : '—'}
      </Paragraph>
    </Block>
  );
}
```

---

### Inline

Skip the popover and render the calendar inline.

```tsx live
<DateInput label="Inline calendar" inline defaultValue={new Date()} />
```

---

### Min and Max

Limit selectable dates to a range.

```tsx live
function example() {
  const today = new Date();
  const min = new Date(today.getFullYear(), today.getMonth(), 1);
  const max = new Date(today.getFullYear(), today.getMonth() + 1, 0);
  return (
    <DateInput
      label="This month only"
      min={min}
      max={max}
      defaultValue={today}
    />
  );
}
```

:::note iOS native does not enforce `min`/`max` in the picker
On iOS Safari the calendar lets the user pick any date; `min`/`max` only fire at form-submission validation ([WebKit bug #225639](https://bugs.webkit.org/show_bug.cgi?id=225639), still open). Pass `mobileNative={false}` for iOS-side enforcement. Android Chrome's native picker does honor them.
:::

**Typing-first** — the same bounds with `openOnFocus={false}`: every keystroke and `↑` / `↓` arrow is clamped to the range (out-of-range candidates are silently rejected), and the launcher icon (or `↓`) opens the calendar.

```tsx live
function example() {
  const now = new Date();
  const min = new Date(now.getFullYear(), now.getMonth(), 1);
  const max = new Date(now.getFullYear(), now.getMonth() + 1, 0);
  return (
    <DateInput
      label="Typing is clamped to this month"
      min={min}
      max={max}
      defaultValue={new Date(now.getFullYear(), now.getMonth(), 15)}
      openOnFocus={false}
    />
  );
}
```

---

### Disabled Dates

Disable specific dates with `shouldDisableDate` (predicate) or `unselectableDates` (array). Blocked dates are disabled in the calendar and rejected during manual typing, the same way `min`/`max` are enforced.

```tsx live
<DateInput
  label="No weekends"
  shouldDisableDate={d => d.getDay() === 0 || d.getDay() === 6}
  mobileNative={false}
/>
```

:::note Forced to the custom calendar
HTML has no equivalent to `shouldDisableDate` or `unselectableDates`, so the OS-native pickers can't block any dates. This example forces `mobileNative={false}` so the rule works on touch devices too; in your app, keep the default `mobileNative="auto"` and also validate in `onChange`.
:::

**Typing-first** — with `openOnFocus={false}` the predicate also vetoes manual entry: typing or arrowing to a weekend is rejected, and the calendar stays tucked behind the launcher icon (or `↓`).

```tsx live
function example() {
  return (
    <DateInput
      label="Weekends rejected while typing"
      shouldDisableDate={d => d.getDay() === 0 || d.getDay() === 6}
      defaultValue={new Date(2024, 5, 7)}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### Custom Format

Use an alternative token format. Supported tokens: `YYYY YY MM M DD D HH H hh h mm m ss s A a`.

```tsx live
<DateInput
  label="Date of birth"
  format="DD/MM/YYYY"
  placeholder="DD/MM/YYYY"
  mobileNative={false}
/>
```

:::note Forced to the custom calendar
The OS-native pickers use the device's locale format and don't render `placeholder` text. This example forces `mobileNative={false}` so the format/placeholder show on touch devices too.
:::

**Typing-first** — the same format with `openOnFocus={false}`: type day-first (typing `/` jumps to the next segment) and reach for the launcher icon (or `↓`) when you want the calendar.

```tsx live
function example() {
  return (
    <DateInput
      label="DD/MM/YYYY"
      format="DD/MM/YYYY"
      defaultValue={new Date(2024, 5, 7)}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### Formats

The `format` prop takes a token string or `Intl.DateTimeFormatOptions`. Padded tokens (`YYYY`, `YY`, `MM`, `DD`) keep the field segmented-typeable; `Intl` formats are display-only unless you also pass a custom `parse`.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateInput
    label="YYYY-MM-DD (default)"
    defaultValue={new Date(2026, 4, 30)}
    openOnFocus={false}
    mobileNative={false}
  />
  <DateInput
    label="DD/MM/YYYY"
    format="DD/MM/YYYY"
    defaultValue={new Date(2026, 4, 30)}
    openOnFocus={false}
    mobileNative={false}
  />
  <DateInput
    label="MM-DD-YYYY"
    format="MM-DD-YYYY"
    defaultValue={new Date(2026, 4, 30)}
    openOnFocus={false}
    mobileNative={false}
  />
  <DateInput
    label="DD.MM.YY"
    format="DD.MM.YY"
    defaultValue={new Date(2026, 4, 30)}
    openOnFocus={false}
    mobileNative={false}
  />
</Block>
```

:::note Forced to the custom calendar
`format` is ignored by the OS-native pickers (they use the device locale), so these examples set `mobileNative={false}` to show the formats on touch devices too.
:::

For an `Intl.DateTimeFormatOptions` format, supply a `parse` so typed text round-trips to a `Date`:

```tsx live
function example() {
  const parse = s => {
    const t = Date.parse(s);
    return isNaN(t) ? null : new Date(t);
  };
  return (
    <DateInput
      label="Intl long + custom parse"
      format={{ year: 'numeric', month: 'long', day: 'numeric' }}
      parse={parse}
      defaultValue={new Date(2026, 4, 30)}
      mobileNative={false}
    />
  );
}
```

**Typing-first** — adding `openOnFocus={false}` here shows free-form entry: Intl formats have no segments, so typed text is committed on Enter or blur, and the calendar opens only via the launcher icon (or `↓`).

```tsx live
function example() {
  const parse = s => {
    const t = Date.parse(s);
    return isNaN(t) ? null : new Date(t);
  };
  return (
    <DateInput
      label="Intl long + custom parse — typing-first"
      format={{ year: 'numeric', month: 'long', day: 'numeric' }}
      parse={parse}
      defaultValue={new Date(2026, 4, 30)}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### Launcher Icon

A clickable launcher sits on the **right** and toggles the popover — handy for input-mode (`openOnFocus={false}`) where you type the value and click the icon to open the calendar. Override its glyph with `triggerIconName`, or hide it with `triggerIcon={false}` (the popover still opens on focus / click). The decorative **left** icon is independent: it shows by default, takes its glyph from `iconLeftName`, and is hidden with `iconLeftName=""`.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateInput label="Default (left icon + right launcher)" />
  <DateInput label="Custom launcher glyph" triggerIconName="calendar-day" />
  <DateInput label="No launcher" triggerIcon={false} />
  <DateInput label="Left icon hidden" iconLeftName="" />
</Block>
```

**Typing-first** — the same group with `openOnFocus={false}`, where the launcher icon earns its keep; note that the `triggerIcon={false}` instance has no launcher, so its popover is keyboard-only (`↓`).

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateInput label="Default (left icon + right launcher)" openOnFocus={false} />
  <DateInput
    label="Custom launcher glyph"
    triggerIconName="calendar-day"
    openOnFocus={false}
  />
  <DateInput
    label="No launcher — popover via ↓ only"
    triggerIcon={false}
    openOnFocus={false}
  />
  <DateInput label="Left icon hidden" iconLeftName="" openOnFocus={false} />
</Block>
```

---

### Manual Keyboard Entry

Focus the input — the **year** segment highlights automatically and you can drive the whole date with the keyboard, never touching the calendar. Press `↑` / `↓` to change a segment, `→` / `←` to move between year, month, and day, or type digits directly. The caret auto-advances over the `-` separators (and typing a separator jumps too). Segment mode activates whenever `format` is a token string with padded tokens (`YYYY`, `YY`, `MM`, `DD`); `Intl.DateTimeFormatOptions` formats and single-character tokens (`Y`, `M`, `D`) fall back to free-form text entry.

These examples use `openOnFocus={false}` so the popover doesn't cover the input — set `openOnFocus={true}` (the default) and both UIs coexist.

:::tip Opening the picker vs. typing
With `openOnFocus={false}` (used here), **clicking the field just lets you type** — the popover does not appear on focus or click. Open the picker by clicking the **launcher icon on the right** (or pressing `↓`). With the default `openOnFocus={true}`, focusing or clicking the field opens the popover immediately (you can still type while it's open).
:::

#### Basic

```tsx live
function example() {
  return (
    <DateInput
      label="Click in, then arrow or type"
      defaultValue={new Date(2024, 5, 7)}
      openOnFocus={false}
    />
  );
}
```

---

#### Digit entry and auto-advance

Type digits to overwrite the active segment. Auto-advance honors each segment's range: the month advances after a first digit ≥ 2 (no month 20+) but waits after `1` (for 10/11/12); the day advances after ≥ 4 but waits after `3` (for 30/31); the year buffers all four digits. Two-digit values clamp (month → 12, day → the month's length).

```tsx live
function example() {
  return (
    <DateInput
      label="Type digits — auto-advance across segments"
      defaultValue={new Date(2024, 5, 7)}
      openOnFocus={false}
    />
  );
}
```

---

#### Controlled with live value

```tsx live
function example() {
  const [v, setV] = useState(() => new Date(2024, 5, 7));
  return (
    <Block>
      <DateInput
        label="Arrow or type — value updates live"
        value={v}
        onChange={setV}
        openOnFocus={false}
      />
      <Paragraph mt="2">Selected: {v ? v.toDateString() : '—'}</Paragraph>
    </Block>
  );
}
```

---

#### Free-form fallback

When `format` is an `Intl.DateTimeFormatOptions` object (or uses single-char tokens), segment mode disables — focusing the input does not highlight a segment, and the input parses on blur instead.

```tsx live
function example() {
  return (
    <DateInput
      label="Free-form (Intl format)"
      format={{ year: 'numeric', month: 'long', day: 'numeric' }}
      defaultValue={new Date(2024, 5, 7)}
      openOnFocus={false}
    />
  );
}
```

---

### Picker vs Input Modes

Two booleans choose how the field behaves. `editable` controls whether segmented typing is allowed; `popover` controls whether the calendar exists. Both default to `true` (type **and** pick). The four combinations:

| `editable` | `popover` | Behavior                                     |
| ---------- | --------- | -------------------------------------------- |
| `true`     | `true`    | Both — segmented typing + calendar (default) |
| `false`    | `true`    | Picker-only — typing inert, calendar opens   |
| `true`     | `false`   | Input-only — segmented typing, no calendar   |
| `false`    | `false`   | Static display                               |

#### Picker only

Typing is disabled; the calendar still opens on click or focus.

```tsx live
<DateInput label="Picker only" editable={false} defaultValue={new Date()} />
```

#### Input only

Segmented typing with no calendar — handy in dense forms.

```tsx live
<DateInput label="Input only" popover={false} defaultValue={new Date()} />
```

---

### Locale

Day and month names follow the supplied BCP-47 locale via `Intl.DateTimeFormat`.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateInput
    label="ja-JP"
    locale="ja-JP"
    defaultValue={new Date()}
    mobileNative={false}
  />
  <DateInput
    label="fr-FR"
    locale="fr-FR"
    defaultValue={new Date()}
    mobileNative={false}
  />
  <DateInput
    label="de-DE"
    locale="de-DE"
    defaultValue={new Date()}
    mobileNative={false}
  />
</Block>
```

:::note Forced to the custom calendar
The OS-native pickers always use the device's system locale, so these examples set `mobileNative={false}` to show the per-input `locale` on touch devices too.
:::

**Typing-first** — the same locales with `openOnFocus={false}` added: type straight into each field, then compare the localized calendars via the launcher icon (or `↓`).

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateInput
    label="ja-JP"
    locale="ja-JP"
    defaultValue={new Date()}
    mobileNative={false}
    openOnFocus={false}
  />
  <DateInput
    label="fr-FR"
    locale="fr-FR"
    defaultValue={new Date()}
    mobileNative={false}
    openOnFocus={false}
  />
  <DateInput
    label="de-DE"
    locale="de-DE"
    defaultValue={new Date()}
    mobileNative={false}
    openOnFocus={false}
  />
</Block>
```

---

### First Day of Week

Set `firstDayOfWeek` to align the grid to Monday-first locales.

```tsx live
<DateInput label="Week starts Monday" firstDayOfWeek={1} mobileNative={false} />
```

:::note Forced to the custom calendar
The OS-native calendars use the device locale for the week start, so `firstDayOfWeek` (and `dayNames`/`monthNames`/`nearbyMonthDays`) are ignored there. This example forces `mobileNative={false}` so the Monday-first grid shows on touch devices too.
:::

**Typing-first** — the same example with `openOnFocus={false}`: type freely, then open the Monday-first grid with the launcher icon (or `↓`).

```tsx live
<DateInput
  label="Week starts Monday — typing-first"
  firstDayOfWeek={1}
  mobileNative={false}
  openOnFocus={false}
/>
```

---

### Mobile Native

Force the native `<input type="date">` (auto-detected on coarse-pointer + small-viewport devices by default).

```tsx live
<DateInput label="Native picker" mobileNative={true} />
```

:::caution Native picker support varies — iOS lags Android
The OS-native fallback is just an `<input type="date">`, so it inherits each platform's behavior. The custom calendar popover (`mobileNative={false}`) honors every prop on every device.

**Honored on Android Chrome but NOT on iOS Safari:**

- **`min` / `max`** — Android Chrome dims out-of-range dates in the calendar; iOS lets the user pick any date, only firing the constraint at form-submission validation. ([WebKit bug #225639](https://bugs.webkit.org/show_bug.cgi?id=225639), still open as of 2026.)

**Ignored on BOTH iOS Safari and Android Chrome (HTML-spec gaps):**

- **`shouldDisableDate`, `unselectableDates`** — HTML has no predicate or array equivalent; native pickers can't evaluate functions.
- **`firstDayOfWeek`, `dayNames`, `monthNames`, `nearbyMonthDays`** — both use the device's system locale and the OS's own calendar layout.
- **`format`, `locale`, `parse`** — both use the device's system locale; per-input overrides are ignored.
- **`placeholder`** — neither renders placeholder text on date inputs.

If any of these matter, pass `mobileNative={false}` to force the custom calendar popover (works on every device), or duplicate the constraint in `onChange` / server-side validation.
:::

---

### Sizes

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateInput label="Small" controlSize="small" size="small" />
  <DateInput label="Default" />
  <DateInput label="Medium" controlSize="medium" size="medium" />
  <DateInput label="Large" controlSize="large" size="large" />
</Block>
```

**Typing-first** — every size with `openOnFocus={false}` so focusing just lets you type; the launcher icon (or `↓`) opens the popover.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateInput
    label="Small"
    controlSize="small"
    size="small"
    openOnFocus={false}
  />
  <DateInput label="Default" openOnFocus={false} />
  <DateInput
    label="Medium"
    controlSize="medium"
    size="medium"
    openOnFocus={false}
  />
  <DateInput
    label="Large"
    controlSize="large"
    size="large"
    openOnFocus={false}
  />
</Block>
```

---

### Colors

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateInput label="Primary" color="primary" />
  <DateInput label="Info" color="info" />
  <DateInput label="Success" color="success" />
  <DateInput label="Warning" color="warning" />
  <DateInput label="Danger" color="danger" />
</Block>
```

**Typing-first** — the same palette with `openOnFocus={false}`: click in to type, and use the launcher icon (or `↓`) for the calendar.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateInput label="Primary" color="primary" openOnFocus={false} />
  <DateInput label="Info" color="info" openOnFocus={false} />
  <DateInput label="Success" color="success" openOnFocus={false} />
  <DateInput label="Warning" color="warning" openOnFocus={false} />
  <DateInput label="Danger" color="danger" openOnFocus={false} />
</Block>
```

---

### States

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateInput label="Disabled" disabled />
  <DateInput label="Read only" readOnly defaultValue={new Date()} />
  <DateInput label="Loading" isLoading />
</Block>
```

---

### Horizontal Field

```tsx live
<DateInput label="Date of birth" horizontal placeholder="YYYY-MM-DD" />
```

**Typing-first** — the horizontal layout with `openOnFocus={false}`: focusing lets you type straight away, and the launcher icon (or `↓`) opens the popover.

```tsx live
<DateInput
  label="Date of birth"
  horizontal
  placeholder="YYYY-MM-DD"
  openOnFocus={false}
/>
```

---

### Context-Aware Rendering

The `DateInput` component is context-aware: it detects whether it is already inside a `Field` and adjusts its rendering accordingly. You can use it standalone with a `label` prop (it wraps itself in a Field), or inside a `Field` / `Control` (it skips rendering its own).

#### Default (with label)

The simplest usage — the component automatically renders its own Field wrapper.

```tsx live
<DateInput label="Date" placeholder="YYYY-MM-DD" />
```

---

#### With Field Wrapper

Wrap in a `Field` when you need manual layout control. The component detects it and skips rendering its own.

```tsx live
function example() {
  return (
    <Field horizontal label="Date">
      <Field.Body>
        <Field>
          <DateInput placeholder="YYYY-MM-DD" />
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

For full manual composition (e.g. custom icons), wrap in both `Field` and `Control`.

```tsx live
function example() {
  return (
    <Field horizontal label="Date">
      <Field.Body>
        <Field>
          <Control iconLeftName="calendar-alt">
            <DateInput placeholder="YYYY-MM-DD" />
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

## Keyboard Navigation

### On the input (segmented entry)

Focus the input — the **year** segment highlights automatically and the keyboard alone can drive the full date entry without ever opening the popover. Segment mode activates whenever `format` is a token string with padded tokens (`YYYY`, `YY`, `MM`, `DD`); `Intl.DateTimeFormatOptions` formats and single-character tokens (`Y`, `M`, `D`) fall back to free-form text entry that parses on blur.

| Key                           | Action                                                                         |
| ----------------------------- | ------------------------------------------------------------------------------ |
| `↑` / `↓`                     | Increment / decrement the active segment (year / month / day, wraps in place)  |
| `←` / `→`                     | Move to previous / next segment                                                |
| `0`–`9`                       | Overwrite the active segment; auto-advances when no further digit is valid     |
| Separator (`-` `/` `.` space) | Skip to the next segment without inserting the character                       |
| `Backspace`                   | Clear the typed-digit buffer; if already cleared, move to the previous segment |
| `Tab`                         | Clear segment selection so focus moves out naturally                           |
| `Escape`                      | Close the popover                                                              |
| `Enter`                       | Close the popover when `closeOnSelect` (the value is already committed live)   |

Digit auto-advance honors each segment's range: the month advances after a first digit ≥ 2 (no month 20+) but waits after `1` (for 10/11/12); the day advances after ≥ 4 but waits after `3` (for 30/31); the year buffers all four digits. Two-digit values clamp (month → 12, day → the month's length).

### On the popover calendar

| Key                   | Action                            |
| --------------------- | --------------------------------- |
| `↓`                   | Open popover (when closed)        |
| `Enter`               | Parse typed text / select focused |
| `Escape`              | Close popover                     |
| `←` / `→`             | Move focused date by ±1 day       |
| `↑` / `↓`             | Move focused date by ±7 days      |
| `PageUp` / `PageDown` | Move focused date by ±1 month     |
| `Shift+PageUp/Down`   | Move focused date by ±1 year      |
| `Home` / `End`        | Jump to start / end of week       |
| `Space`               | Select focused date               |
| `Tab`                 | Move focus to next control        |

---

## Form Submission

`DateInput` participates in HTML form submission. Pass a `name` and the value is forwarded to a hidden `<input>` formatted as `YYYY-MM-DD`.

| Prop       | Description                                                  |
| ---------- | ------------------------------------------------------------ |
| `name`     | Form field name.                                             |
| `form`     | Optional id of the form the input belongs to.                |
| `required` | Marks the field as required for native HTML form validation. |

```tsx live
function DateInputFormDemo() {
  const [submitted, setSubmitted] = React.useState('');
  return (
    <form
      onSubmit={e => {
        e.preventDefault();
        const fd = new FormData(e.currentTarget);
        setSubmitted(JSON.stringify(Array.from(fd.entries()), null, 2));
      }}
    >
      <DateInput
        name="booking"
        label="Booking date"
        defaultValue={new Date()}
        required
      />
      
        <button type="submit" className="button is-primary">
          Submit
        </button>
      
      {submitted && <pre style={{ marginTop: '1rem' }}>{submitted}</pre>}
    </form>
  );
}
```

---

## Accessibility

- Trigger uses `role="combobox"` with `aria-haspopup="dialog"`, `aria-expanded`, and `aria-controls`.
- Popover panel has `role="dialog"` with an accessible name.
- Calendar uses `role="grid"` with cells as `role="gridcell"`.
- Cells expose `aria-selected`, `aria-disabled`, and `aria-current="date"` for today.
- Roving `tabindex` keeps a single grid cell focusable at a time.
- Honors `prefers-reduced-motion` (skip popover fade-in).

---

## Related Components

- [TimeInput](./timeinput.md) - Time-of-day picker with a spinner.
- [DateTimeInput](./datetimeinput.md) - Combined date + time picker.
- [Input](../input.md) - For basic text input.

---

## Additional Resources

- [Storybook: DateInput Stories](https://bestax.io/storybook/?path=/story/form-dateinput)

:::tip Pro Tip
Use `inline` instead of the popover when you have vertical room to spare — booking grids and dashboards feel more direct without the open/close ceremony.
:::

---

## DateTimeInput


## Overview

The `DateTimeInput` combines a calendar and a time **wheel spinner** in a single popover — an iOS-style layout. The popover opens to the **calendar** with an iOS-style footer: the selected **time** as a tappable value, a **Reset** button (reverts your edits to the value the popover opened with), and a circular **✓** confirm button. **Clicking the time floats the wheel spinner over the calendar** (hours, minutes, and optionally seconds — the same wheels the `TimeInput` uses), so the popover never grows or scrolls; clicking the time again, clicking outside the wheel card, or pressing `Escape` hides it. It supports the full prop surface of both `DateInput` and `TimeInput`, plus a native `<input type="datetime-local">` fallback for touch devices. A clickable launcher icon on the right opens the popover, and you can type directly in the field with segmented keyboard entry.

---

## Import

```tsx

```

---

## Props

The DateTimeInput prop set is the union of [DateInput](./dateinput.md) and [TimeInput](./timeinput.md) props. Notable additions and overrides:

| Prop                | Type                                     | Default              | Description                                                                                                                                                   |
| ------------------- | ---------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`             | `Date \| null`                           | —                    | Controlled selected date-time.                                                                                                                                |
| `defaultValue`      | `Date \| null`                           | —                    | Initial value for uncontrolled usage.                                                                                                                         |
| `onChange`          | `(d: Date \| null) => void`              | —                    | Fired when either the date or time portion changes.                                                                                                           |
| `format`            | `string \| Intl.DateTimeFormatOptions`   | `'YYYY-MM-DD HH:mm'` | Token format string or `Intl.DateTimeFormat` options.                                                                                                         |
| `closeOnSelect`     | `boolean`                                | `false`              | Off by default — users typically tweak both halves before committing.                                                                                         |
| `editable`          | `boolean`                                | `true`               | Allow segmented keyboard typing (type the date-time directly across all segments). `false` makes the field picker-only.                                       |
| `popover`           | `boolean`                                | `true`               | Whether the calendar + time popover exists. `false` makes the field input-only.                                                                               |
| `incrementMinutes`  | `number`                                 | `1`                  | Step between minute-wheel values (`1` = every minute, iOS-style).                                                                                             |
| `incrementSeconds`  | `number`                                 | `1`                  | Step between second-wheel values (only with `enableSeconds`).                                                                                                 |
| `iconLeftName`      | `string`                                 | `'calendar-alt'`     | Decorative left icon glyph for the wrapping `Control` (shown by default). Set `''` to hide.                                                                   |
| `triggerIcon`       | `boolean`                                | `true`               | Show a clickable launcher button on the right that toggles the popover.                                                                                       |
| `triggerIconName`   | `string`                                 | `'chevron-down'`     | Glyph for the right launcher button.                                                                                                                          |
| `mobileNative`      | `boolean \| 'auto'`                      | `'auto'`             | Use `<input type="datetime-local">` on coarse-pointer devices.                                                                                                |
| `min` / `max`       | `Date`                                   | —                    | Bounds enforced across both date and time.                                                                                                                    |
| `shouldDisableDate` | `(d: Date) => boolean`                   | —                    | Disable specific dates. Blocked dates are also rejected during manual typing (the predicate receives the full candidate date-time — prefer day-based checks). |
| `unselectableTimes` | `(d: Date) => boolean`                   | —                    | Block specific times. Blocked times are also rejected during manual typing.                                                                                   |
| `firstDayOfWeek`    | `0..6`                                   | `0`                  | Calendar week start.                                                                                                                                          |
| `hourFormat`        | `'12' \| '24'`                           | `'24'`               | Time format.                                                                                                                                                  |
| `enableSeconds`     | `boolean`                                | `false`              | Show seconds column. Note: iOS Safari's native datetime-local picker UI does not include a seconds wheel; pass `mobileNative={false}` if you need one on iOS. |
| ...                 | All DateInput + TimeInput props          |                      | See those pages for the full list.                                                                                                                            |
| ...                 | All standard HTML and Bulma helper props |                      | (See [Helper Props](../../helpers/usebulmaclasses))                                                                                                           |

When you pass an explicit token `format`, **that format is the source of truth for the time wheels and the footer time pill**: a 12-hour format (`h`/`hh` with `A`/`a`) drives a 12-hour wheel with an AM/PM column, and a 24-hour format (`H`/`HH`) drives a 24-hour wheel — regardless of `hourFormat`. So `hourFormat` only applies when you don't pass a `format`. (If `format` is an `Intl.DateTimeFormat` options object rather than a token string, the cycle can't be read from it and the wheel/pill fall back to `hourFormat`.)

---

## Usage

### Basic DateTimeInput

The popover opens to the calendar with an iOS-style footer — the selected time, a **Reset** button, and a circular **✓** to confirm. Click the time value to float the wheel spinner over the calendar.

```tsx live
<DateTimeInput label="Appointment" placeholder="YYYY-MM-DD HH:MM" />
```

**Typing-first** — the same example with `openOnFocus={false}`: focusing or clicking the field lets you type; open the popover with the launcher icon (or press `↓`).

```tsx live
<DateTimeInput
  label="Appointment"
  placeholder="YYYY-MM-DD HH:MM"
  openOnFocus={false}
/>
```

---

### Controlled

```tsx live
function example() {
  const [v, setV] = useState(new Date());
  return (
    <Block>
      <DateTimeInput label="Meeting" value={v} onChange={setV} />
      <Paragraph mt="2">Selected: {v ? v.toString() : '—'}</Paragraph>
    </Block>
  );
}
```

**Typing-first** — the same controlled example with `openOnFocus={false}` added: click in and type freely, and reach for the launcher icon (or `↓`) when you want the popover.

```tsx live
function example() {
  const [v, setV] = useState(new Date());
  return (
    <Block>
      <DateTimeInput
        label="Meeting"
        value={v}
        onChange={setV}
        openOnFocus={false}
      />
      <Paragraph mt="2">Selected: {v ? v.toString() : '—'}</Paragraph>
    </Block>
  );
}
```

---

### 12-hour Format

```tsx live
<DateTimeInput
  label="12-hour"
  hourFormat="12"
  defaultValue={new Date()}
  mobileNative={false}
/>
```

:::note Forced to the custom popover
The OS-native pickers use the device clock setting, so `hourFormat` is ignored there. This example forces `mobileNative={false}` so the 12-hour format shows on touch devices too.
:::

**Typing-first** — the same 12-hour field with `openOnFocus={false}`: type across the segments (press `a` / `p` on the trailing meridiem) and open the popover with the launcher icon or `↓`.

```tsx live
function example() {
  return (
    <DateTimeInput
      label="12-hour entry"
      hourFormat="12"
      defaultValue={new Date(2024, 5, 7, 13, 45)}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### With Seconds

```tsx live
<DateTimeInput
  label="With seconds"
  enableSeconds
  defaultValue={new Date()}
  mobileNative={false}
/>
```

:::caution iOS Safari has no seconds wheel (Android Chrome shows one with caveats)
This example forces `mobileNative={false}` so the seconds wheel shows on every device.
**Android Chrome** generally renders a seconds component in its native datetime-local picker when `step < 60` (with [some long-standing quirks](https://bugs.chromium.org/p/chromium/issues/detail?id=461718) — exact seconds-spinner behavior varies by Android version). **iOS Safari** has no seconds wheel under any circumstances. If you need a guaranteed seconds wheel, pass `mobileNative={false}` to force the custom wheel popover. See [Mobile Native](#mobile-native) below for the full iOS-vs-Android picker support matrix.
:::

**Typing-first** — the same seconds-enabled field with `openOnFocus={false}`: the typed walk gains a seconds segment (year → month → day → hours → minutes → seconds), and the launcher icon (or `↓`) opens the popover.

```tsx live
function example() {
  return (
    <DateTimeInput
      label="With a seconds segment"
      enableSeconds
      defaultValue={new Date(2024, 5, 7, 13, 45, 30)}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### 12-hour with Seconds

Combine `hourFormat="12"` with `enableSeconds` for an `hh:mm:ss A` field — the wheel gains hours, minutes, seconds, and AM/PM columns.

```tsx live
<DateTimeInput
  label="12-hour with seconds"
  hourFormat="12"
  enableSeconds
  defaultValue={new Date()}
  mobileNative={false}
/>
```

:::note Forced to the custom popover
The OS-native pickers honor neither half: `hourFormat` follows the device clock setting, and iOS Safari has no seconds wheel at all. This example forces `mobileNative={false}` so the 12-hour seconds wheel shows on every device.
:::

**Typing-first** — the full segment set with `openOnFocus={false}`: type through date, `hh`, `mm`, `ss`, toggle the trailing meridiem with `a` / `p`, and open the popover via the launcher icon or `↓`.

```tsx live
function example() {
  return (
    <DateTimeInput
      label="12-hour with seconds and AM/PM"
      hourFormat="12"
      enableSeconds
      defaultValue={new Date(2024, 5, 7, 13, 45, 30)}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### Formats

The `format` prop takes a token string or `Intl.DateTimeFormatOptions` spanning the whole date-time. Padded token formats keep the field segmented-typeable; `Intl` formats are display-only unless you add a custom `parse`.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateTimeInput
    label="YYYY-MM-DD HH:mm (default)"
    defaultValue={new Date(2026, 4, 30, 13, 45)}
    mobileNative={false}
  />
  <DateTimeInput
    label="MM/DD/YYYY hh:mm A"
    format="MM/DD/YYYY hh:mm A"
    defaultValue={new Date(2026, 4, 30, 13, 45)}
    mobileNative={false}
  />
  <DateTimeInput
    label="DD.MM.YYYY HH:mm"
    format="DD.MM.YYYY HH:mm"
    defaultValue={new Date(2026, 4, 30, 13, 45)}
    mobileNative={false}
  />
  <DateTimeInput
    label="Intl — display only"
    format={{ dateStyle: 'medium', timeStyle: 'short' }}
    editable={false}
    defaultValue={new Date(2026, 4, 30, 13, 45)}
    mobileNative={false}
  />
</Block>
```

:::note Forced to the custom popover
`format` is ignored by the OS-native pickers (they use the device locale), so these examples set `mobileNative={false}` to show the formats on touch devices too.
:::

**Typing-first** — a custom `DD.MM.YYYY HH:mm` format with `openOnFocus={false}`: segments follow the format order (day first) and typing `.`, space, or `:` jumps the separators — so `25.12.2026 09:30` flows straight through — with the launcher icon (or `↓`) opening the popover.

```tsx live
function example() {
  return (
    <DateTimeInput
      label="DD.MM.YYYY HH:mm with dot separators"
      format="DD.MM.YYYY HH:mm"
      defaultValue={new Date(2024, 5, 7, 13, 45)}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### Launcher Icon

A clickable launcher sits on the **right** and toggles the popover — handy for input-mode (`openOnFocus={false}`) where you type the value and click the icon to open the picker. Override its glyph with `triggerIconName`, or hide it with `triggerIcon={false}` (the popover still opens on focus / click). The decorative **left** icon is independent: it shows by default, takes its glyph from `iconLeftName`, and is hidden with `iconLeftName=""`.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateTimeInput label="Default (left icon + right launcher)" />
  <DateTimeInput
    label="Custom launcher glyph"
    triggerIconName="calendar-check"
  />
  <DateTimeInput label="No launcher" triggerIcon={false} />
  <DateTimeInput label="Left icon hidden" iconLeftName="" />
</Block>
```

**Typing-first** — the same group with `openOnFocus={false}` on every instance, so clicking a field just lets you type and the launcher icon opens the popover; note the `triggerIcon={false}` instance has no launcher, leaving its popover keyboard-only via `↓`.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateTimeInput
    label="Default (left icon + right launcher)"
    openOnFocus={false}
  />
  <DateTimeInput
    label="Custom launcher glyph"
    triggerIconName="calendar-check"
    openOnFocus={false}
  />
  <DateTimeInput
    label="No launcher (popover via ↓ only)"
    triggerIcon={false}
    openOnFocus={false}
  />
  <DateTimeInput label="Left icon hidden" iconLeftName="" openOnFocus={false} />
</Block>
```

---

### Min and Max

Bounds apply to the combined date-time.

```tsx live
function example() {
  const today = new Date();
  const min = new Date(today);
  min.setHours(9, 0, 0, 0);
  const max = new Date(today);
  max.setHours(17, 0, 0, 0);
  return <DateTimeInput label="Office hours today" min={min} max={max} />;
}
```

:::note iOS native does not enforce `min`/`max` in the picker
On iOS Safari the picker UI lets the user pick any value; `min`/`max` only fire at form-submission validation ([WebKit bug #225639](https://bugs.webkit.org/show_bug.cgi?id=225639), still open). Pass `mobileNative={false}` for iOS-side enforcement. Android Chrome's native picker does honor them.
:::

**Typing-first** — the same bounds with `openOnFocus={false}`: keystrokes and `↑` / `↓` arrows never produce a value outside `min`/`max`, and the launcher icon (or `↓`) opens the popover.

```tsx live
function example() {
  const now = new Date();
  const min = new Date(now);
  min.setHours(9, 0, 0, 0);
  const max = new Date(now);
  max.setHours(17, 0, 0, 0);
  const noon = new Date(now);
  noon.setHours(12, 0, 0, 0);
  return (
    <DateTimeInput
      label="Office hours today only — typed entry too"
      min={min}
      max={max}
      defaultValue={noon}
      openOnFocus={false}
    />
  );
}
```

---

### Disabled Dates

Blocked dates are disabled in the calendar and rejected during manual typing, the same way `min`/`max` are enforced.

```tsx live
<DateTimeInput
  label="No weekend appointments"
  shouldDisableDate={d => d.getDay() === 0 || d.getDay() === 6}
  mobileNative={false}
/>
```

:::note Forced to the custom popover
HTML has no predicate equivalent, so the OS-native pickers can't block any dates. This example forces `mobileNative={false}` so the rule works on touch devices; in your app keep `mobileNative="auto"` and also validate in `onChange`.
:::

**Typing-first** — the same predicate with `openOnFocus={false}`: a keystroke or arrow that lands on a blocked date is rejected (matching the disabled calendar cells), and the launcher icon (or `↓`) opens the popover.

```tsx live
function example() {
  return (
    <DateTimeInput
      label="Weekends rejected while typing"
      shouldDisableDate={d => d.getDay() === 0 || d.getDay() === 6}
      defaultValue={new Date(2024, 5, 7, 13, 45)}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### Unselectable Times

Blocked times are skipped by the wheels and rejected during manual typing.

```tsx live
<DateTimeInput
  label="Lunch hour blocked"
  unselectableTimes={d => d.getHours() === 12}
  defaultValue={new Date()}
  mobileNative={false}
/>
```

:::note Forced to the custom popover
Same as Disabled Dates — the OS-native pickers can't evaluate predicates. This example forces `mobileNative={false}` so the blocked hour works on touch devices too.
:::

**Typing-first** — the same blocked hour with `openOnFocus={false}`: setting the hour segment to a blocked hour is vetoed by the `unselectableTimes` predicate (just as the wheels skip it), and the launcher icon (or `↓`) opens the popover.

```tsx live
function example() {
  return (
    <DateTimeInput
      label="Lunch hour rejected while typing"
      unselectableTimes={d => d.getHours() === 12}
      defaultValue={new Date(2024, 5, 7, 11, 30)}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### Inline

```tsx live
<DateTimeInput label="Inline" inline defaultValue={new Date()} />
```

---

### First Day of Week

```tsx live
<DateTimeInput
  label="Monday-first"
  firstDayOfWeek={1}
  defaultValue={new Date()}
  mobileNative={false}
/>
```

:::note Forced to the custom popover
The OS-native calendars use the device locale for the week start, so `firstDayOfWeek` is ignored there. This example forces `mobileNative={false}` so the Monday-first grid shows on touch devices too.
:::

**Typing-first** — the same Monday-first example with `openOnFocus={false}`: type in the field directly and bring up the popover with the launcher icon (or `↓`) to see the week start.

```tsx live
<DateTimeInput
  label="Monday-first"
  firstDayOfWeek={1}
  defaultValue={new Date()}
  mobileNative={false}
  openOnFocus={false}
/>
```

---

### Mobile Native

By default `mobileNative='auto'`: on touch devices with a small viewport (`(pointer: coarse)` and `(max-width: 768px)`) the input swaps to a plain `<input type="datetime-local">` so the OS-native picker handles the interaction. Pass `true` or `false` to override.

```tsx live
<DateTimeInput label="Native datetime-local" mobileNative={true} />
```

:::caution Native picker support varies — iOS lags Android
The OS-native fallback is just a `<input type="datetime-local">`, so it inherits each platform's behavior. The custom popover (`mobileNative={false}`) honors every prop on every device.

**Honored on Android Chrome but NOT on iOS Safari:**

- **`min` / `max`** — Android Chrome dims out-of-range values in the picker; iOS lets the user pick any value, only firing the constraint at form-submission validation. ([WebKit bug #225639](https://bugs.webkit.org/show_bug.cgi?id=225639), still open as of 2026.)
- **`incrementMinutes`, `incrementHours`** — Android Chrome respects `step` (e.g. only 0/15/30/45 minutes selectable when `step=900`). iOS shows every value regardless.
- **`enableSeconds`** — Android Chrome shows a seconds component when `step < 60` (with [some long-standing quirks for `datetime-local`](https://bugs.chromium.org/p/chromium/issues/detail?id=461718)). iOS has no seconds wheel under any circumstances.

**Ignored on BOTH iOS Safari and Android Chrome (HTML-spec gaps):**

- **`shouldDisableDate`, `unselectableDates`, `unselectableTimes`** — HTML has no predicate/array equivalent; native pickers can't evaluate functions.
- **`firstDayOfWeek`, `dayNames`, `monthNames`, `nearbyMonthDays`** — both use the device's system locale.
- **`hourFormat`** — both use the device's system clock setting (12h/24h).
- **`format`, `locale`** — both use the device's system locale; per-input overrides are ignored.
- **`placeholder`** — neither renders placeholder text.

If any of these matter, pass `mobileNative={false}` to force the custom popover (works on every device), or duplicate the constraint in `onChange` / server-side validation.
:::

---

### Locale

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateTimeInput
    label="ja-JP"
    locale="ja-JP"
    defaultValue={new Date()}
    mobileNative={false}
  />
  <DateTimeInput
    label="fr-FR"
    locale="fr-FR"
    defaultValue={new Date()}
    mobileNative={false}
  />
</Block>
```

:::note Forced to the custom popover
The OS-native pickers always use the device's system locale, so these examples set `mobileNative={false}` to show the per-input `locale` on touch devices too.
:::

**Typing-first** — the same locales with `openOnFocus={false}` on each instance: focus to type the localized value, and use the launcher icon (or `↓`) to open the popover.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateTimeInput
    label="ja-JP"
    locale="ja-JP"
    defaultValue={new Date()}
    mobileNative={false}
    openOnFocus={false}
  />
  <DateTimeInput
    label="fr-FR"
    locale="fr-FR"
    defaultValue={new Date()}
    mobileNative={false}
    openOnFocus={false}
  />
</Block>
```

---

### Sizes

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateTimeInput label="Small" controlSize="small" size="small" />
  <DateTimeInput label="Default" />
  <DateTimeInput label="Medium" controlSize="medium" size="medium" />
  <DateTimeInput label="Large" controlSize="large" size="large" />
</Block>
```

**Typing-first** — every size with `openOnFocus={false}`: clicking any field lets you type straight away, with the launcher icon (or `↓`) opening the popover.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateTimeInput
    label="Small"
    controlSize="small"
    size="small"
    openOnFocus={false}
  />
  <DateTimeInput label="Default" openOnFocus={false} />
  <DateTimeInput
    label="Medium"
    controlSize="medium"
    size="medium"
    openOnFocus={false}
  />
  <DateTimeInput
    label="Large"
    controlSize="large"
    size="large"
    openOnFocus={false}
  />
</Block>
```

---

### Colors

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateTimeInput label="Primary" color="primary" />
  <DateTimeInput label="Info" color="info" />
  <DateTimeInput label="Success" color="success" />
  <DateTimeInput label="Warning" color="warning" />
  <DateTimeInput label="Danger" color="danger" />
</Block>
```

**Typing-first** — the same colors with `openOnFocus={false}` on every instance: type directly in any field and open the popover with the launcher icon (or `↓`).

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateTimeInput label="Primary" color="primary" openOnFocus={false} />
  <DateTimeInput label="Info" color="info" openOnFocus={false} />
  <DateTimeInput label="Success" color="success" openOnFocus={false} />
  <DateTimeInput label="Warning" color="warning" openOnFocus={false} />
  <DateTimeInput label="Danger" color="danger" openOnFocus={false} />
</Block>
```

---

### States

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <DateTimeInput label="Disabled" disabled />
  <DateTimeInput label="Read only" readOnly defaultValue={new Date()} />
  <DateTimeInput label="Loading" isLoading />
</Block>
```

---

### Context-Aware Rendering

#### Default (with label)

```tsx live
<DateTimeInput label="When" placeholder="YYYY-MM-DD HH:MM" />
```

---

#### With Field Wrapper

```tsx live
function example() {
  return (
    <Field horizontal label="When">
      <Field.Body>
        <Field>
          <DateTimeInput placeholder="YYYY-MM-DD HH:MM" />
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

```tsx live
function example() {
  return (
    <Field horizontal label="When">
      <Field.Body>
        <Field>
          <Control iconLeftName="calendar-alt">
            <DateTimeInput placeholder="YYYY-MM-DD HH:MM" />
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

### Manual Keyboard Entry

The single input spans the whole date-time: year → month → day → hours → minutes (plus seconds / AM-PM when enabled). Focus highlights the **year**; `↑` / `↓` adjust a segment, `→` / `←` move between them, digits overwrite with auto-advance, and typing a `-`, space, or `:` jumps across the separators. Segment mode activates whenever `format` is a token string with padded tokens (`YYYY`, `MM`, `DD`, `HH`/`hh`, `mm`, `ss`, `A`); `Intl.DateTimeFormatOptions` formats and single-character tokens fall back to free-form text.

These examples use `openOnFocus={false}` so the popover doesn't cover the input.

:::tip Opening the picker vs. typing
With `openOnFocus={false}` (used here), **clicking the field just lets you type** — the popover does not appear on focus or click. Open the picker by clicking the **launcher icon on the right** (or pressing `↓`). With the default `openOnFocus={true}`, focusing or clicking the field opens the popover immediately (you can still type while it's open).
:::

#### Basic

```tsx live
function example() {
  return (
    <DateTimeInput
      label="Type across date and time"
      defaultValue={new Date(2024, 5, 7, 13, 45)}
      openOnFocus={false}
    />
  );
}
```

---

#### Controlled with live value

```tsx live
function example() {
  const [v, setV] = useState(() => new Date(2024, 5, 7, 13, 45));
  return (
    <Block>
      <DateTimeInput
        label="Arrow or type — value updates live"
        value={v}
        onChange={setV}
        openOnFocus={false}
      />
      <Paragraph mt="2">Selected: {v ? v.toString() : '—'}</Paragraph>
    </Block>
  );
}
```

---

#### Free-form fallback

An `Intl.DateTimeFormatOptions` format has no segment map, so entry is free-form — focusing does not highlight a segment and the text parses on Enter or blur instead.

```tsx live
function example() {
  return (
    <DateTimeInput
      label="Free-form (Intl format)"
      format={{ dateStyle: 'medium', timeStyle: 'short' }}
      defaultValue={new Date(2024, 5, 7, 13, 45)}
      openOnFocus={false}
    />
  );
}
```

---

### Picker vs Input Modes

`editable` controls whether segmented typing is allowed; `popover` controls whether the calendar + time panel exists. Both default to `true`.

| `editable` | `popover` | Behavior                                    |
| ---------- | --------- | ------------------------------------------- |
| `true`     | `true`    | Both — segmented typing + popover (default) |
| `false`    | `true`    | Picker-only — typing inert, popover opens   |
| `true`     | `false`   | Input-only — segmented typing, no popover   |
| `false`    | `false`   | Static display                              |

#### Picker only

```tsx live
<DateTimeInput label="Picker only" editable={false} defaultValue={new Date()} />
```

#### Input only

```tsx live
<DateTimeInput label="Input only" popover={false} defaultValue={new Date()} />
```

---

## Keyboard Navigation

### On the input (segmented entry)

A single field spans year → month → day → hours → minutes (→ seconds → AM/PM when enabled). Focus highlights the year; segment mode activates whenever `format` is a token string with padded tokens (`YYYY`, `MM`, `DD`, `HH`, `hh`, `mm`, `ss`, `A`); `Intl` formats and single-character tokens fall back to free-form text entry.

| Key                               | Action                                                                         |
| --------------------------------- | ------------------------------------------------------------------------------ |
| `↑` / `↓`                         | Increment / decrement the active segment (wraps in place)                      |
| `←` / `→`                         | Move to previous / next segment                                                |
| `0`–`9`                           | Overwrite the active segment; auto-advances when no further digit is valid     |
| `a` / `A` / `p` / `P`             | Toggle AM/PM on the meridiem segment (12-hour formats)                         |
| Separator (`-` `/` `:` `.` space) | Skip to the next segment without inserting the character                       |
| `Backspace`                       | Clear the typed-digit buffer; if already cleared, move to the previous segment |
| `Tab`                             | Clear segment selection so focus moves out naturally                           |
| `Escape`                          | Close the popover                                                              |

### On the popover

| Key                   | Action                                          |
| --------------------- | ----------------------------------------------- |
| `↓`                   | Open popover (when closed)                      |
| `Escape`              | Close popover                                   |
| `←` / `→`             | Move focused date by ±1 day                     |
| `↑` / `↓`             | Move focused date by ±7 days                    |
| `PageUp` / `PageDown` | Move focused date by ±1 month                   |
| `Shift+PageUp/Down`   | Move focused date by ±1 year                    |
| `Home` / `End`        | Jump to start / end of week                     |
| `Enter` / `Space`     | Select focused date                             |
| `Tab`                 | Move focus from calendar → time button → footer |

Activate the footer **time** button (`Enter` / `Space`) to float the wheels over the calendar. On a time wheel: `↑` / `↓` change the value, `←` / `→` move between the hours / minutes / (seconds) columns, and `Enter` commits and closes. While the wheels are open, `Escape` collapses them (a second `Escape` closes the popover), and clicking anywhere outside the wheel card dismisses them.

---

## Form Submission

| Prop       | Description                                                  |
| ---------- | ------------------------------------------------------------ |
| `name`     | Form field name.                                             |
| `form`     | Optional id of the form the input belongs to.                |
| `required` | Marks the field as required for native HTML form validation. |

```tsx live
function DateTimeInputFormDemo() {
  const [submitted, setSubmitted] = React.useState('');
  return (
    <form
      onSubmit={e => {
        e.preventDefault();
        const fd = new FormData(e.currentTarget);
        setSubmitted(JSON.stringify(Array.from(fd.entries()), null, 2));
      }}
    >
      <DateTimeInput name="when" label="When" required />
      
        <button type="submit" className="button is-primary">
          Submit
        </button>
      
      {submitted && <pre style={{ marginTop: '1rem' }}>{submitted}</pre>}
    </form>
  );
}
```

---

## Accessibility

- Trigger uses `role="combobox"` with `aria-haspopup="dialog"`, `aria-expanded`, and `aria-controls`.
- Popover panel has `role="dialog"` with an accessible name.
- Calendar uses `role="grid"`; cells expose `aria-selected`, `aria-disabled`, and `aria-current="date"`.
- Each time wheel uses `role="spinbutton"` with `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, and `aria-valuetext`.
- The footer's confirm button exposes an accessible label (`Done`); the Reset button reverts your edits to the value the popover opened with.
- Tab order naturally walks from calendar → time wheels → footer (Reset / ✓).

---

## Related Components

- [DateInput](./dateinput.md) - Date-only picker.
- [TimeInput](./timeinput.md) - Time-only picker.
- [Input](../input.md) - For basic text input.

---

## Additional Resources

- [Storybook: DateTimeInput Stories](https://bestax.io/storybook/?path=/story/form-datetimeinput)

:::tip Pro Tip
Pair `DateTimeInput` with `closeOnSelect={false}` (the default) so users can tweak both date and time before committing via OK — closing on the first date click would surprise them.
:::

---

## TimeInput


## Overview

The `TimeInput` component is a form input that opens a popover spinner for time-of-day selection. A clickable launcher icon on the right opens the popover, and you can type directly in the field with segmented keyboard entry. It supports 12-hour and 24-hour formats, optional seconds, custom hour/minute/second increments, min/max bounds, an unselectable-times predicate, and a native `<input type="time">` fallback for touch devices.

---

## Import

```tsx

```

---

## Props

| Prop                | Type                                                                     | Default          | Description                                                                                                                                                                                                                        |
| ------------------- | ------------------------------------------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`             | `Date \| null`                                                           | —                | Controlled selected time (date portion is preserved).                                                                                                                                                                              |
| `defaultValue`      | `Date \| null`                                                           | —                | Initial value for uncontrolled usage.                                                                                                                                                                                              |
| `onChange`          | `(d: Date \| null) => void`                                              | —                | Fired when the value changes.                                                                                                                                                                                                      |
| `onOpen`            | `() => void`                                                             | —                | Fired when the popover opens.                                                                                                                                                                                                      |
| `onClose`           | `() => void`                                                             | —                | Fired when the popover closes.                                                                                                                                                                                                     |
| `min`               | `Date`                                                                   | —                | Earliest selectable time.                                                                                                                                                                                                          |
| `max`               | `Date`                                                                   | —                | Latest selectable time.                                                                                                                                                                                                            |
| `hourFormat`        | `'12' \| '24'`                                                           | `'24'`           | Hour format. `'12'` shows an AM/PM toggle.                                                                                                                                                                                         |
| `enableSeconds`     | `boolean`                                                                | `false`          | Show a seconds column. Note: iOS Safari's native time picker UI does not include a seconds wheel; pass `mobileNative={false}` if you need one on iOS.                                                                              |
| `incrementHours`    | `number`                                                                 | `1`              | Hour step for the spinner.                                                                                                                                                                                                         |
| `incrementMinutes`  | `number`                                                                 | `1`              | Minute step. Combine with `min`/`max` for slot-style pickers.                                                                                                                                                                      |
| `incrementSeconds`  | `number`                                                                 | `1`              | Second step.                                                                                                                                                                                                                       |
| `unselectableTimes` | `(d: Date) => boolean`                                                   | —                | Predicate returning `true` for times that should be skipped. Blocked times are also rejected during manual typing.                                                                                                                 |
| `placeholder`       | `string`                                                                 | —                | Placeholder text for the input.                                                                                                                                                                                                    |
| `format`            | `string \| Intl.DateTimeFormatOptions`                                   | (see below)      | Token format string or `Intl.DateTimeFormat` options.                                                                                                                                                                              |
| `parse`             | `(s: string) => Date \| null`                                            | —                | Custom parser.                                                                                                                                                                                                                     |
| `locale`            | `string`                                                                 | —                | BCP-47 locale tag for Intl formatting.                                                                                                                                                                                             |
| `inline`            | `boolean`                                                                | `false`          | Render the spinner inline (no popover).                                                                                                                                                                                            |
| `mobileNative`      | `boolean \| 'auto'`                                                      | `'auto'`         | Use `<input type="time">` on coarse-pointer + small-viewport devices.                                                                                                                                                              |
| `audioTick`         | `boolean`                                                                | `false`          | Play a short audible click on each wheel-item crossing. Substitute for haptic feedback on iOS Safari (which has no web haptic API as of May 2026); on Android, `navigator.vibrate(5)` fires automatically regardless.              |
| `haptics`           | `boolean`                                                                | `false`          | Auto-route platform-appropriate feedback: vibrate on Android (already happening), audio thunk on iOS (where vibrate is unavailable). One switch instead of platform-sniffing on the consumer side. `audioTick={true}` always wins. |
| `editable`          | `boolean`                                                                | `true`           | Allow segmented keyboard typing in the input (type the time directly, auto-advancing across segments). `false` makes the field picker-only.                                                                                        |
| `popover`           | `boolean`                                                                | `true`           | Whether the spinner popover exists. `false` makes the field input-only (segmented typing, no popover).                                                                                                                             |
| `openOnFocus`       | `boolean`                                                                | `true`           | Open the popover when the input is focused.                                                                                                                                                                                        |
| `closeOnSelect`     | `boolean`                                                                | `false`          | Close the popover after a time is selected (off by default).                                                                                                                                                                       |
| `position`          | `'bottom-left' \| 'bottom-right' \| 'top-left' \| 'top-right' \| 'auto'` | `'bottom-left'`  | Popover anchor position relative to the input.                                                                                                                                                                                     |
| `appendToBody`      | `boolean`                                                                | `false`          | Render the popover into `document.body` via portal.                                                                                                                                                                                |
| `disabled`          | `boolean`                                                                | `false`          | Disable the input.                                                                                                                                                                                                                 |
| `readOnly`          | `boolean`                                                                | `false`          | Make the input read-only.                                                                                                                                                                                                          |
| `color`             | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`    | —                | Bulma color modifier.                                                                                                                                                                                                              |
| `size`              | `'small' \| 'medium' \| 'large'`                                         | —                | Size variant.                                                                                                                                                                                                                      |
| `isRounded`         | `boolean`                                                                | `false`          | Render the input with rounded corners.                                                                                                                                                                                             |
| `iconLeftName`      | `string`                                                                 | `'clock'`        | Decorative left icon glyph for the wrapping `Control` (shown by default). Set `''` to hide.                                                                                                                                        |
| `triggerIcon`       | `boolean`                                                                | `true`           | Show a clickable launcher button on the right that toggles the popover.                                                                                                                                                            |
| `triggerIconName`   | `string`                                                                 | `'chevron-down'` | Glyph for the right launcher button.                                                                                                                                                                                               |
| `name`              | `string`                                                                 | —                | Form field name.                                                                                                                                                                                                                   |
| `form`              | `string`                                                                 | —                | Form id the input belongs to.                                                                                                                                                                                                      |
| `required`          | `boolean`                                                                | `false`          | Marks the input as required.                                                                                                                                                                                                       |
| `label`             | `React.ReactNode`                                                        | —                | Field label.                                                                                                                                                                                                                       |
| `horizontal`        | `boolean`                                                                | `false`          | Render the field with horizontal layout.                                                                                                                                                                                           |
| `message`           | `React.ReactNode`                                                        | —                | Help/validation text below the input.                                                                                                                                                                                              |
| `messageColor`      | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`    | —                | Color modifier for the help message.                                                                                                                                                                                               |
| `className`         | `string`                                                                 | —                | Additional CSS classes for the input.                                                                                                                                                                                              |
| `ref`               | `React.Ref<HTMLInputElement>`                                            | —                | Forwarded to the underlying `<input>`.                                                                                                                                                                                             |
| ...                 | All standard HTML and Bulma helper props                                 |                  | (See [Helper Props](../../helpers/usebulmaclasses))                                                                                                                                                                                |

The default `format` depends on `hourFormat` and `enableSeconds`: `'HH:mm'`, `'HH:mm:ss'`, `'hh:mm A'`, or `'hh:mm:ss A'`.

When you pass an explicit token `format`, **that format is the source of truth for the wheel spinner**: a 12-hour format (`h`/`hh` with `A`/`a`) shows a 12-hour wheel with an AM/PM column, and a 24-hour format (`H`/`HH`) shows a 24-hour wheel — regardless of `hourFormat`. So `hourFormat` only matters when you don't pass a `format`. (If `format` is an `Intl.DateTimeFormat` options object rather than a token string, the cycle can't be read from it and the wheel falls back to `hourFormat`.)

---

## Usage

### Basic TimeInput

```tsx live
<TimeInput label="Time" placeholder="HH:MM" />
```

**Typing-first** — the same example with `openOnFocus={false}`: focusing or clicking the field lets you type; open the popover with the launcher icon (or press `↓`).

```tsx live
<TimeInput label="Time" placeholder="HH:MM" openOnFocus={false} />
```

---

### Controlled

```tsx live
function example() {
  const [v, setV] = useState(() => {
    const d = new Date();
    d.setHours(13, 45, 0, 0);
    return d;
  });
  return (
    <Block>
      <TimeInput label="Departure" value={v} onChange={setV} />
      <Paragraph mt="2">Selected: {v ? v.toLocaleTimeString() : '—'}</Paragraph>
    </Block>
  );
}
```

**Typing-first** — the same controlled example with `openOnFocus={false}`: focus and type freely; the launcher icon on the right (or `↓`) opens the popover.

```tsx live
function example() {
  const [v, setV] = useState(() => {
    const d = new Date();
    d.setHours(13, 45, 0, 0);
    return d;
  });
  return (
    <Block>
      <TimeInput
        label="Departure"
        value={v}
        onChange={setV}
        openOnFocus={false}
      />
      <Paragraph mt="2">Selected: {v ? v.toLocaleTimeString() : '—'}</Paragraph>
    </Block>
  );
}
```

---

### 12-hour Format

`hourFormat="12"` renders an AM/PM toggle column.

```tsx live
function example() {
  const v = new Date();
  v.setHours(13, 45, 0, 0);
  return (
    <TimeInput
      label="12-hour"
      hourFormat="12"
      defaultValue={v}
      mobileNative={false}
    />
  );
}
```

:::note Forced to the custom wheel
The OS-native pickers use the device's clock setting (12h/24h), so `hourFormat` is ignored there. This example forces `mobileNative={false}` so the 12-hour format shows on touch devices too.
:::

**Typing-first** — identical, but with `openOnFocus={false}` so focusing lets you type (press `a` / `p` on the AM/PM segment); the launcher icon (or `↓`) opens the popover.

```tsx live
function example() {
  const v = new Date();
  v.setHours(13, 45, 0, 0);
  return (
    <TimeInput
      label="Press a / A / p / P on AM-PM"
      hourFormat="12"
      defaultValue={v}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### 24-hour Format

The default. Hours run 00–23.

```tsx live
function example() {
  const v = new Date();
  v.setHours(13, 45, 0, 0);
  return (
    <TimeInput
      label="24-hour"
      hourFormat="24"
      defaultValue={v}
      mobileNative={false}
    />
  );
}
```

:::note Forced to the custom wheel
Same as above — the OS-native pickers follow the device clock setting. This example forces `mobileNative={false}` to show 24-hour on touch devices.
:::

**Typing-first** — the same 24-hour example with `openOnFocus={false}`: click in and type the time; the launcher icon (or `↓`) brings up the popover.

```tsx live
function example() {
  const v = new Date();
  v.setHours(13, 45, 0, 0);
  return (
    <TimeInput
      label="24-hour"
      hourFormat="24"
      defaultValue={v}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### With Seconds

Adds a third spinner column.

```tsx live
function example() {
  const v = new Date();
  v.setHours(10, 20, 30, 0);
  return (
    <TimeInput
      label="With seconds"
      enableSeconds
      defaultValue={v}
      mobileNative={false}
    />
  );
}
```

:::caution iOS Safari has no seconds wheel (Android Chrome does)
This example forces `mobileNative={false}` so the seconds wheel shows on every device.
**Android Chrome** renders a seconds spinner in its native time picker when `step < 60` (which our component sets when `enableSeconds` is true). **iOS Safari** has no seconds wheel under any circumstances — Apple's native picker UI is hard-locked to hour/minute spinners regardless of `step`. The input value can carry seconds entered programmatically, but iOS users can't pick them in the wheel. If you need a seconds wheel on iOS, pass `mobileNative={false}` to force the custom wheel popover. See [Mobile Native](#mobile-native) below for the full iOS-vs-Android picker support matrix.
:::

**Typing-first** — the same example plus `openOnFocus={false}`: type across the hours / minutes / seconds segments, and open the popover with the launcher icon (or `↓`).

```tsx live
function example() {
  const v = new Date();
  v.setHours(10, 20, 30, 0);
  return (
    <TimeInput
      label="Tab through hours / minutes / seconds"
      enableSeconds
      defaultValue={v}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### Increment Steps

Pair `incrementMinutes` with min/max for slot-style pickers.

```tsx live
function example() {
  const v = new Date();
  v.setHours(9, 30, 0, 0);
  return (
    <TimeInput
      label="15-minute slots"
      incrementMinutes={15}
      defaultValue={v}
      mobileNative={false}
    />
  );
}
```

:::note Forced to the custom wheel
iOS Safari shows every minute regardless of `step`. This example forces `mobileNative={false}` so the 15-minute stepping is enforced on every device.
:::

**Typing-first** — the same example with `openOnFocus={false}`: increments only step the wheels, not typing — typed values are free-grained — so open the stepped wheels with the launcher icon (or `↓`).

```tsx live
function example() {
  const v = new Date();
  v.setHours(9, 30, 0, 0);
  return (
    <TimeInput
      label="15-minute wheels — typing is free-grained"
      incrementMinutes={15}
      defaultValue={v}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### Min and Max

Restrict to a time-of-day range.

```tsx live
function example() {
  const today = new Date();
  const min = new Date(today);
  min.setHours(9, 0, 0, 0);
  const max = new Date(today);
  max.setHours(17, 0, 0, 0);
  const dv = new Date(today);
  dv.setHours(12, 0, 0, 0);
  return (
    <TimeInput
      label="Office hours: 09:00 — 17:00"
      min={min}
      max={max}
      defaultValue={dv}
    />
  );
}
```

:::note iOS native does not enforce `min`/`max` in the picker
On iOS Safari the picker UI lets the user spin to any time; `min`/`max` only fire at form-submission validation ([WebKit bug #225639](https://bugs.webkit.org/show_bug.cgi?id=225639), still open). Pass `mobileNative={false}` for iOS-side enforcement. Android Chrome's native picker does honor them.
:::

**Typing-first** — the same bounds with `openOnFocus={false}`: typed entry is clamped to the window just like the wheels; open the popover with the launcher icon (or `↓`).

```tsx live
function example() {
  const at = (h, m) => {
    const d = new Date();
    d.setHours(h, m, 0, 0);
    return d;
  };
  return (
    <TimeInput
      label="Typed entry clamped to 09:00 – 17:00"
      min={at(9, 0)}
      max={at(17, 0)}
      defaultValue={at(12, 0)}
      openOnFocus={false}
    />
  );
}
```

---

### Unselectable Times

Skip times that match a predicate. Blocked values render dimmed in the wheel so the constraint is visible, the per-item button gets the `disabled` attribute (so clicks no-op), and keyboard / wheel scrolling automatically advances past them via the `nextValid` lookahead. The disabled state is dynamic — it's evaluated against the _other_ columns' current values, so e.g. a predicate that blocks only `12:00–12:59` leaves all minutes enabled once the user moves the hour off 12. Manual typing also rejects blocked times, the same way `min`/`max` are enforced.

```tsx live
function example() {
  const v = new Date();
  v.setHours(11, 30, 0, 0);
  return (
    <TimeInput
      label="Lunch hour blocked"
      unselectableTimes={d => d.getHours() === 12}
      defaultValue={v}
      mobileNative={false}
    />
  );
}
```

:::note Forced to the custom wheel
HTML has no predicate equivalent, so the OS-native pickers can't block any times. This example forces `mobileNative={false}` so the rule works on touch devices; in your app keep `mobileNative="auto"` and also validate in `onChange`.
:::

**Typing-first** — the same predicate with `openOnFocus={false}`: typing or arrowing into a blocked time is rejected just like in the wheels, and the launcher icon (or `↓`) opens the popover.

```tsx live
function example() {
  const v = new Date();
  v.setHours(11, 30, 0, 0);
  return (
    <TimeInput
      label="Lunch hour rejected while typing"
      unselectableTimes={d => d.getHours() === 12}
      defaultValue={v}
      mobileNative={false}
      openOnFocus={false}
    />
  );
}
```

---

### Manual Keyboard Entry

Focus the input — the **hours** segment highlights automatically and the keyboard alone can drive the full time entry without ever opening the popover. Segment mode activates whenever the `format` is a token string with padded tokens (`HH`, `hh`, `mm`, `ss`, `A`, `a`); custom `Intl.DateTimeFormatOptions` formats and unpadded tokens (`H`, `h`, `m`, `s`) fall back to free-form text entry.

These examples use `openOnFocus={false}` so the popover doesn't cover the input — set `openOnFocus={true}` (the default) and both UIs coexist. To turn segment typing off entirely, pass `editable={false}` (picker-only); to drop the popover and keep only the field, pass `popover={false}` (input-only).

:::tip Opening the picker vs. typing
With `openOnFocus={false}` (used here), **clicking the field just lets you type** — the popover does not appear on focus or click. Open the picker by clicking the **launcher icon on the right** (or pressing `↓`). With the default `openOnFocus={true}`, focusing or clicking the field opens the popover immediately (you can still type while it's open).
:::

#### Basic

Click into the field, then press `↑` / `↓` to change the hours, `→` to move to minutes, and continue.

```tsx live
function example() {
  const v = new Date();
  v.setHours(13, 45, 0, 0);
  return (
    <TimeInput
      label="Click in, then use arrow keys"
      defaultValue={v}
      openOnFocus={false}
    />
  );
}
```

---

#### Digit entry and auto-advance

Type digits to overwrite the active segment. The picker auto-advances when no further digit could form a valid value — for 24-hour hours, typing `5` advances immediately (no `50–59` to wait for), but typing `2` waits for an optional second digit (`20`–`23` are still valid). Minutes/seconds advance after any digit `6`–`9`, since `60`+ is out of range.

```tsx live
function example() {
  const v = new Date();
  v.setHours(9, 0, 0, 0);
  return (
    <TimeInput
      label="Type digits — auto-advance after each segment"
      defaultValue={v}
      openOnFocus={false}
    />
  );
}
```

---

#### Controlled with live value

The value updates on every increment, digit, or AM/PM toggle — exactly like the wheel popover. Bind to `useState` to see it.

```tsx live
function example() {
  const [v, setV] = useState(() => {
    const d = new Date();
    d.setHours(13, 45, 0, 0);
    return d;
  });
  return (
    <Block>
      <TimeInput
        label="Arrow or type — value updates live"
        value={v}
        onChange={setV}
        openOnFocus={false}
      />
      <Paragraph mt="2">Selected: {v ? v.toLocaleTimeString() : '—'}</Paragraph>
    </Block>
  );
}
```

---

#### Free-form fallback

When `format` is an `Intl.DateTimeFormatOptions` object (or uses unpadded tokens like `H:m`), segment mode silently disables — focusing the input does not highlight a segment, arrow keys fall through to default behavior, and the input parses on blur instead.

```tsx live
function example() {
  const v = new Date();
  v.setHours(13, 45, 0, 0);
  return (
    <TimeInput
      label="Free-form (Intl format)"
      format={{ hour: '2-digit', minute: '2-digit' }}
      defaultValue={v}
      openOnFocus={false}
    />
  );
}
```

---

#### 12-hour with seconds

The full segment walk: `hh` → `mm` → `ss` → AM/PM. `→` / `←` move through all four segments, digits overwrite with auto-advance, and `a` / `p` toggle the meridiem.

```tsx live
function example() {
  const v = new Date();
  v.setHours(13, 45, 30, 0);
  return (
    <TimeInput
      label="hh:mm:ss + AM/PM"
      hourFormat="12"
      enableSeconds
      defaultValue={v}
      openOnFocus={false}
    />
  );
}
```

---

### Haptic-feel Feedback (audio tick + band pulse)

The custom-wheel popover fires three kinds of feedback per item crossing to make the picker feel tactile across platforms:

- **Haptic (Android only)** — `navigator.vibrate(5)` fires unconditionally on Android Chrome / Firefox Android / Samsung Internet. iOS Safari does not expose `navigator.vibrate`, and Apple patched the `<input type="checkbox" switch>` workaround in iOS 26.5 — there is no longer any web-only path to the Taptic Engine.
- **Audio thunk (opt-in via `audioTick`)** — a 160 Hz triangle-wave tone sweeping down to 110 Hz over ~30 ms. The low fundamental and downward pitch sweep are tuned to read as a body-felt thump rather than an ear-felt beep, matching the proprioceptive signature of native Taptic UI pops.
- **Visual band pulse (always-on)** — the selection band briefly scales (`1 → 1.04 → 1`) and brightens (`× 1.15`) over 110 ms on every tick. Single-element Web Animations API call with `composite: 'replace'` so rapid fling ticks restart cleanly. Respects `prefers-reduced-motion: reduce`.

```tsx live
function example() {
  const v = new Date();
  v.setHours(9, 30, 0, 0);
  return (
    <TimeInput
      label="Audio thunk + band pulse"
      audioTick
      mobileNative={false}
      defaultValue={v}
    />
  );
}
```

**Typing-first** — the same example with `openOnFocus={false}`: typing stays silent — the audio thunk and band pulse fire once you open the wheels via the launcher icon (or `↓`) and scroll them.

```tsx live
function example() {
  const v = new Date();
  v.setHours(9, 30, 0, 0);
  return (
    <TimeInput
      label="Audio thunk + band pulse"
      audioTick
      mobileNative={false}
      defaultValue={v}
      openOnFocus={false}
    />
  );
}
```

For a single switch that picks the right feedback per platform automatically — vibrate on Android, audio thunk on iOS — use `haptics` instead of `audioTick`:

```tsx live
function example() {
  const v = new Date();
  v.setHours(9, 30, 0, 0);
  return (
    <TimeInput
      label="Auto-routed haptics"
      haptics
      mobileNative={false}
      defaultValue={v}
    />
  );
}
```

**Typing-first** — the same auto-routed feedback with `openOnFocus={false}`: the vibrate/thunk fires when you open the wheels with the launcher icon (or `↓`) and scroll them, not while typing.

```tsx live
function example() {
  const v = new Date();
  v.setHours(9, 30, 0, 0);
  return (
    <TimeInput
      label="Auto-routed haptics"
      haptics
      mobileNative={false}
      defaultValue={v}
      openOnFocus={false}
    />
  );
}
```

`haptics` feature-detects `navigator.vibrate` rather than UA-sniffing. On Android (vibrate present), no audio is layered on top of the real haptic; on iOS (vibrate absent), the audio thunk fills in.

:::note Behaviour details

- `audioTick` is off by default; opt in per-instance.
- Android still fires haptic via `navigator.vibrate` independently — enabling `audioTick` adds the audible thunk on top.
- The visual band pulse is always-on and gated only by `prefers-reduced-motion`; no prop needed.
- The first wheel touch unlocks the `AudioContext` (Web Audio's gesture requirement); subsequent ticks play with no further user action.
- The iPhone silent switch (and Android system volume) suppress the tick audio — matching native UX expectations.
- Native iOS wrappers (Capacitor, React Native + WebView) can bridge to `UIImpactFeedbackGenerator` for real Taptic feedback; the audio thunk + visual pulse together are the closest pure-web equivalent.
  :::

---

### Inline

Render the spinner directly without a popover.

```tsx live
function example() {
  const v = new Date();
  v.setHours(8, 30, 0, 0);
  return <TimeInput label="Inline" inline defaultValue={v} />;
}
```

---

### Mobile Native

By default `mobileNative='auto'`: on touch devices with a small viewport (`(pointer: coarse)` and `(max-width: 768px)`) the input swaps to a plain `<input type="time">` so the OS-native time picker handles the interaction. On desktop the custom wheel popover renders. Pass `true` or `false` to override the auto-detection.

:::caution Native picker support varies — iOS lags Android
The OS-native fallback is just a `<input type="time">`, so it inherits each platform's behavior. The custom wheel popover (`mobileNative={false}`) honors every prop on every device.

**Honored on Android Chrome but NOT on iOS Safari:**

- **`min` / `max`** — Android dims out-of-range times in the wheel; iOS lets the user spin to any value, only firing the constraint at form-submission validation. ([WebKit bug #225639](https://bugs.webkit.org/show_bug.cgi?id=225639), still open as of 2026.)
- **`incrementMinutes`, `incrementHours`, `incrementSeconds`** — Android Chrome respects `step` (e.g. only 0/15/30/45 minutes selectable when `step=900`). iOS shows every value regardless.
- **`enableSeconds`** — Android Chrome shows a seconds spinner when `step < 60`. iOS has no seconds wheel under any circumstances.

**Ignored on BOTH iOS Safari and Android Chrome (HTML-spec gaps):**

- **`unselectableTimes`** — HTML has no predicate equivalent; native pickers can't evaluate functions.
- **`hourFormat`** — both use the device's system clock setting (12h/24h).
- **`format`, `locale`** — both use the device's system locale; per-input overrides are ignored.
- **`placeholder`** — neither renders placeholder text on time inputs.

If any of these matter, pass `mobileNative={false}` to force the custom wheel popover (works on every device), or duplicate the constraint in `onChange` / server-side validation.
:::

#### Force native

```tsx live
<TimeInput label="Always native" mobileNative={true} />
```

#### Force the custom wheel (even on mobile)

Useful when you want the same wheel UI everywhere — for example, if your app already provides a touch-friendly viewport-sized picker.

```tsx live
<TimeInput label="Always custom wheel" mobileNative={false} />
```

---

### Formats

The `format` prop takes a token string or `Intl.DateTimeFormatOptions`. The same time rendered several ways:

```tsx live
function example() {
  const v = new Date();
  v.setHours(13, 45, 30, 0);
  return (
    <Block display="flex" flexDirection="column" gap="4">
      <TimeInput label="HH:mm (24h, default)" defaultValue={v} />
      <TimeInput label="hh:mm A (12h)" format="hh:mm A" defaultValue={v} />
      <TimeInput
        label="hh:mm a (lowercase)"
        format="hh:mm a"
        defaultValue={v}
      />
      <TimeInput label="HH:mm:ss" format="HH:mm:ss" defaultValue={v} />
      <TimeInput label="hh:mm:ss A" format="hh:mm:ss A" defaultValue={v} />
    </Block>
  );
}
```

**Typing-first** — the same token formats with `openOnFocus={false}` on every instance: type into the segments each format defines; the launcher icon (or `↓`) opens the popover.

```tsx live
function example() {
  const v = new Date();
  v.setHours(13, 45, 30, 0);
  return (
    <Block display="flex" flexDirection="column" gap="4">
      <TimeInput
        label="HH:mm (24h, default)"
        defaultValue={v}
        openOnFocus={false}
      />
      <TimeInput
        label="hh:mm A (12h)"
        format="hh:mm A"
        defaultValue={v}
        openOnFocus={false}
      />
      <TimeInput
        label="hh:mm a (lowercase)"
        format="hh:mm a"
        defaultValue={v}
        openOnFocus={false}
      />
      <TimeInput
        label="HH:mm:ss"
        format="HH:mm:ss"
        defaultValue={v}
        openOnFocus={false}
      />
      <TimeInput
        label="hh:mm:ss A"
        format="hh:mm:ss A"
        defaultValue={v}
        openOnFocus={false}
      />
    </Block>
  );
}
```

Padded token formats support segmented typing; the meridiem (`A`/`a`) and seconds (`ss`) segments appear when the format includes them. Token formats render the same regardless of `locale`; pass an `Intl.DateTimeFormatOptions` object for locale-aware output (display-only unless you add a custom `parse`).

```tsx live
function example() {
  const v = new Date();
  v.setHours(13, 45, 0, 0);
  return (
    <TimeInput
      label="Intl, fr-FR (display only)"
      format={{ hour: '2-digit', minute: '2-digit' }}
      locale="fr-FR"
      editable={false}
      defaultValue={v}
      mobileNative={false}
    />
  );
}
```

:::note Forced to the custom wheel
`format` and `locale` are ignored by the OS-native pickers (they use the device locale). This example forces `mobileNative={false}` so the locale-aware display shows on touch devices too.
:::

---

### Launcher Icon

A clickable launcher sits on the **right** and toggles the popover — handy for input-mode (`openOnFocus={false}`) where you type the value and click the icon to open the spinner. Override its glyph with `triggerIconName`, or hide it with `triggerIcon={false}` (the popover still opens on focus / click). The decorative **left** icon is independent: it shows by default, takes its glyph from `iconLeftName`, and is hidden with `iconLeftName=""`.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <TimeInput label="Default (left icon + right launcher)" />
  <TimeInput label="Custom launcher glyph" triggerIconName="hourglass" />
  <TimeInput label="No launcher" triggerIcon={false} />
  <TimeInput label="Left icon hidden" iconLeftName="" />
</Block>
```

**Typing-first** — the same set with `openOnFocus={false}` on each instance: the field is type-first, which makes the right launcher icon (or `↓`) the way into the popover.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <TimeInput label="Default (left icon + right launcher)" openOnFocus={false} />
  <TimeInput
    label="Custom launcher glyph"
    triggerIconName="hourglass"
    openOnFocus={false}
  />
  <TimeInput
    label="No launcher (press ↓ to open)"
    triggerIcon={false}
    openOnFocus={false}
  />
  <TimeInput label="Left icon hidden" iconLeftName="" openOnFocus={false} />
</Block>
```

---

### Sizes

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <TimeInput label="Small" controlSize="small" size="small" />
  <TimeInput label="Default" />
  <TimeInput label="Medium" controlSize="medium" size="medium" />
  <TimeInput label="Large" controlSize="large" size="large" />
</Block>
```

**Typing-first** — the same sizes with `openOnFocus={false}` on every instance: focusing lets you type, and the launcher icon (or `↓`) opens the popover.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <TimeInput
    label="Small"
    controlSize="small"
    size="small"
    openOnFocus={false}
  />
  <TimeInput label="Default" openOnFocus={false} />
  <TimeInput
    label="Medium"
    controlSize="medium"
    size="medium"
    openOnFocus={false}
  />
  <TimeInput
    label="Large"
    controlSize="large"
    size="large"
    openOnFocus={false}
  />
</Block>
```

---

### Colors

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <TimeInput label="Primary" color="primary" />
  <TimeInput label="Info" color="info" />
  <TimeInput label="Success" color="success" />
  <TimeInput label="Warning" color="warning" />
  <TimeInput label="Danger" color="danger" />
</Block>
```

**Typing-first** — the same colors with `openOnFocus={false}` everywhere: click in to type, and use the launcher icon (or `↓`) to open the popover.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <TimeInput label="Primary" color="primary" openOnFocus={false} />
  <TimeInput label="Info" color="info" openOnFocus={false} />
  <TimeInput label="Success" color="success" openOnFocus={false} />
  <TimeInput label="Warning" color="warning" openOnFocus={false} />
  <TimeInput label="Danger" color="danger" openOnFocus={false} />
</Block>
```

---

### States

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <TimeInput label="Disabled" disabled />
  <TimeInput label="Read only" readOnly defaultValue={new Date()} />
  <TimeInput label="Loading" isLoading />
</Block>
```

---

### Context-Aware Rendering

The `TimeInput` component is context-aware: it detects whether it is already inside a `Field` and adjusts its rendering accordingly.

#### Default (with label)

```tsx live
<TimeInput label="Time" placeholder="HH:MM" />
```

---

#### With Field Wrapper

```tsx live
function example() {
  return (
    <Field horizontal label="Time">
      <Field.Body>
        <Field>
          <TimeInput placeholder="HH:MM" />
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

```tsx live
function example() {
  return (
    <Field horizontal label="Time">
      <Field.Body>
        <Field>
          <Control iconLeftName="clock">
            <TimeInput placeholder="HH:MM" />
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

## Keyboard Navigation

### On the input (segmented entry)

Focus the input — the **hours** segment is automatically highlighted. Segment mode activates whenever the `format` is a token string with padded tokens (`HH`, `hh`, `mm`, `ss`, `A`, `a`); Intl-options formats and variable-width tokens (`H`, `h`, `m`, `s`) fall back to free-form text entry.

| Key                   | Action                                                                         |
| --------------------- | ------------------------------------------------------------------------------ |
| `↑` / `↓`             | Increment / decrement the active segment (wraps at boundaries)                 |
| `←` / `→`             | Move to previous / next segment (hour ↔ minute ↔ second ↔ AM/PM)               |
| `0`–`9`               | Overwrite the active segment; auto-advances when no further digit is valid     |
| `a` / `A` / `p` / `P` | Toggle AM/PM on the meridiem segment                                           |
| `Backspace`           | Clear the typed-digit buffer; if already cleared, move to the previous segment |
| `Tab`                 | Clear segment selection so focus moves out naturally                           |
| `Escape`              | Close popover                                                                  |
| `Enter`               | Close popover when `closeOnSelect={true}` (value is already committed live)    |

### On a wheel column (when the popover is open)

| Key                   | Action                               |
| --------------------- | ------------------------------------ |
| `↑` / `↓`             | Increment / decrement focused column |
| `PageUp` / `PageDown` | Increment / decrement by 5×          |
| `Tab`                 | Move focus to next column            |
| `Enter`               | Commit live value, close popover     |

---

## Form Submission

`TimeInput` participates in HTML form submission. Pass a `name` and the value is forwarded as `HH:MM` (or `HH:MM:SS` if `enableSeconds`).

| Prop       | Description                                                  |
| ---------- | ------------------------------------------------------------ |
| `name`     | Form field name.                                             |
| `form`     | Optional id of the form the input belongs to.                |
| `required` | Marks the field as required for native HTML form validation. |

```tsx live
function TimeInputFormDemo() {
  const [submitted, setSubmitted] = React.useState('');
  return (
    <form
      onSubmit={e => {
        e.preventDefault();
        const fd = new FormData(e.currentTarget);
        setSubmitted(JSON.stringify(Array.from(fd.entries()), null, 2));
      }}
    >
      <TimeInput name="appointment" label="Appointment time" required />
      
        <button type="submit" className="button is-primary">
          Submit
        </button>
      
      {submitted && <pre style={{ marginTop: '1rem' }}>{submitted}</pre>}
    </form>
  );
}
```

---

## Accessibility

- Trigger uses `role="combobox"` with `aria-haspopup="dialog"`, `aria-expanded`, and `aria-controls`.
- Popover panel has `role="dialog"` with an accessible name.
- Each spinner column has `role="spinbutton"` with `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, and `aria-valuetext`.
- AM/PM toggle exposes `aria-pressed`.
- Honors `prefers-reduced-motion`.

---

## Related Components

- [DateInput](./dateinput.md) - Date-only picker with a calendar popover.
- [DateTimeInput](./datetimeinput.md) - Combined date + time picker.
- [Input](../input.md) - For basic text input.

---

## Additional Resources

- [Storybook: TimeInput Stories](https://bestax.io/storybook/?path=/story/form-timeinput)

:::tip Pro Tip
Combine `incrementMinutes={5}` (or `15`/`30`) with `min` and `max` to build a tight slot picker — the spinner will only land on valid slots.
:::

---

## Field


## Overview

The `Field` component is a Bulma-styled form field container. It supports horizontal layouts, grouped controls, labels, label sizing, and all Bulma helper props for color, margin, and more. `Field` is the primary way to compose labeled, grouped, or horizontal layouts in your forms.

---

## Import

```tsx

// Field.Label, Field.Body are available as subcomponents
```

---

## Props

| Field        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                                         |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------- |
| `horizontal` | `boolean`                                                                                                                                                                                                                                                                                | —       | Renders the field as horizontal (label and control side by side).   |
| `grouped`    | `boolean` \| `'centered'` \| `'right'` \| `'multiline'`                                                                                                                                                                                                                                  | —       | Group controls in a row (optionally centered, right, or multiline). |
| `hasAddons`  | `boolean`                                                                                                                                                                                                                                                                                | —       | Group controls as addons.                                           |
| `label`      | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Field label.                                                        |
| `labelSize`  | `'small'` \| `'normal'` \| `'medium'` \| `'large'`                                                                                                                                                                                                                                       | —       | Size for the label.                                                 |
| `labelProps` | `object` (Label HTML attributes)                                                                                                                                                                                                                                                         | —       | Props for the label element.                                        |
| `textColor`  | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color for the field.                                           |
| `color`      | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`                                                                                                                                                                                                          | —       | Bulma color for the field.                                          |
| `bgColor`    | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color for the field.                                     |
| `className`  | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                                             |
| `children`   | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Field content.                                                      |
| ...          | All Bulma helper and HTML props                                                                                                                                                                                                                                                          | —       | (See [Helper Props](../helpers/usebulmaclasses))                    |

---

## Usage

### With Checkbox

This example demonstrates using the `Field` component to label a single `Checkbox`. The `label` prop provides the field label, and the `Checkbox` is rendered as the field's content.

```tsx live
<Field label="Stay Signed In">
  <Checkbox>Stay Signed In</Checkbox>
</Field>
```

---

### With Checkbox and Custom Label (with link)

Use the `Field` component to group a `Checkbox` with a custom label containing a link. This pattern is useful for agreements or terms and conditions.

```tsx live
<Field label="Agreement">
  <Checkbox>
    I have read and agree to the{' '}
    
      terms and conditions
    
    .
  </Checkbox>
</Field>
```

---

### With Grouped Checkboxes

This example shows how to use the `Field` component to label a group of checkboxes. The `Checkboxes` component is used as the field content, and each `Checkbox` receives its own label.

```tsx live
<Field label="Chores">
  <Checkboxes>
    <Checkbox>Make the bed</Checkbox>
    <Checkbox>Brush teeth</Checkbox>
    <Checkbox>Do homework</Checkbox>
  </Checkboxes>
</Field>
```

---

### With File

This example demonstrates using the `Field` component to label a file upload control. The `File` component is used as the field's content, with a custom label for the file input.

```tsx live
<Field label="Upload Resume">
  <File label="Choose a file..." />
</Field>
```

---

### With Input (Default)

The `Field` component can be used to wrap an `Input` control, providing a label and styling. In this example, a default-styled `Input` is used.

```tsx live
<Field label="Default">
  <Control>
    <Input placeholder="Default input" />
  </Control>
</Field>
```

---

### With Input (Sizes)

This example demonstrates using the `Field` component with `Input` controls of various sizes. The `size` prop on `Input` controls the visual size of the input.

```tsx live
<>
  <Field label="Small">
    <Control>
      <Input size="small" placeholder="Small input" />
    </Control>
  </Field>

  <Field label="Normal">
    <Control>
      <Input placeholder="Normal input" />
    </Control>
  </Field>

  <Field label="Medium">
    <Control>
      <Input size="medium" placeholder="Medium input" />
    </Control>
  </Field>

  <Field label="Large">
    <Control>
      <Input size="large" placeholder="Large input" />
    </Control>
  </Field>
</>
```

---

### With Input (Rounded)

This example shows how to create a `Field` with a rounded `Input`. The `isRounded` prop on `Input` gives it a pill-shaped appearance.

```tsx live
<Field label="Rounded">
  <Control>
    <Input isRounded placeholder="Rounded input" />
  </Control>
</Field>
```

---

### With Input (States)

The `Field` component can be used with `Input` controls to demonstrate different states like hover, focus, and loading. This example shows how to apply these states to an `Input`.

```tsx live
<>
  <Field label="Normal">
    <Control>
      <Input placeholder="Normal state" />
    </Control>
  </Field>

  <Field label="Hover">
    <Control>
      <Input isHovered placeholder="Hovered state" />
    </Control>
  </Field>

  <Field label="Focus">
    <Control>
      <Input isFocused placeholder="Focused state" />
    </Control>
  </Field>

  <Field label="Loading">
    <Control isLoading>
      <Input placeholder="Loading state" />
    </Control>
  </Field>
</>
```

---

### With Input (Disabled & Read Only)

This example demonstrates using the `Field` component with `Input` controls that are disabled or read-only. The `disabled` and `readOnly` props control the respective states of the `Input`.

```tsx live
<>
  <Field label="Disabled">
    <Control>
      <Input disabled placeholder="Disabled input" />
    </Control>
  </Field>

  <Field label="Read Only">
    <Control>
      <Input readOnly value="Read only value" />
    </Control>
  </Field>
</>
```

---

### With Input (Static, Horizontal)

You can use the `Field` component to create horizontal layouts for static and editable inputs. This example shows a static `Input` next to an editable one.

```tsx live
<>
  <Field horizontal label="Username">
    <Control>
      <Input isStatic value="Static value" />
    </Control>
  </Field>
  <Field horizontal label="Password">
    <Control>
      <Input placeholder="Editable value" />
    </Control>
  </Field>
</>
```

---

### With Input (Icons)

This example demonstrates adding icons to an `Input` within a `Field`. The `hasIconsLeft` and `hasIconsRight` props add icons to the left and right of the input, respectively.

```tsx live
<Field>
  <Control
    hasIconsLeft
    hasIconsRight
    iconLeft={{ name: 'user' }}
    iconRight={{ name: 'check' }}
  >
    <Input placeholder="With icons" />
  </Control>
</Field>
```

---

### With Radio

The `Field` component can be used to group `Radio` buttons. In this example, two `Radio` buttons are grouped under the "Pet" label.

```tsx live
<Field label="Pet">
  <Control>
    <Radio name="pet">Cat</Radio>
    <Radio name="pet" defaultChecked>
      Dog
    </Radio>
  </Control>
</Field>
```

---

### With Grouped Radios

This example shows how to use the `Field` component to create a group of `Radio` buttons that are disabled. The `Radios` component is used to group the `Radio` buttons.

```tsx live
<Field label="Event Response">
  <Radios>
    <Radio name="event" disabled>
      Attend
    </Radio>
    <Radio name="event" disabled>
      Decline
    </Radio>
    <Radio name="event" disabled>
      Tentative
    </Radio>
  </Radios>
</Field>
```

---

### With Select

The `Field` component can be used with a `Select` dropdown. This example shows a basic `Select` with two options.

```tsx live
<Field label="Default">
  <Control>
    <Select>
      <option value="">Please select</option>
      <option value="option1">Option 1</option>
      <option value="option2">Option 2</option>
    </Select>
  </Control>
</Field>
```

---

### With Select (Multi Select)

This example demonstrates using the `Field` component with a multi-select `Select`. The `multiple` and `multipleSize` props on `Select` enable multiple selections.

```tsx live
<>
  <Field label="Multi Select">
    <Control>
      <Select multiple multipleSize={10}>
        <option value="huck">Huckleberry Finn</option>
        <option value="tom">Tom Sawyer</option>
        <option value="becky">Becky Thatcher</option>
        <option value="jim">Jim</option>
        <option value="pap">Pap Finn</option>
        <option value="duke">The Duke</option>
        <option value="king">The King</option>
        <option value="widow">Widow Douglas</option>
        <option value="judge">Judge Thatcher</option>
        <option value="sid">Sid Sawyer</option>
      </Select>
    </Control>
  </Field>
  
  
  
  
  
  
  
  
  
  
  
  
  
</>
```

---

### With Select (Colors, Sizes, Rounded, Loading, Icons)

In this example, the `Field` component is used with a `Select` that has various enhancements: color, rounded corners, loading state, and icons.

```tsx live
<>
  <Field label="Primary">
    <Control>
      <Select color="primary">
        <option value="1">Option 1</option>
        <option value="2">Option 2</option>
      </Select>
    </Control>
  </Field>

  <Field label="Rounded">
    <Control>
      <Select isRounded>
        <option value="">Please select</option>
        <option value="option1">Option 1</option>
        <option value="option2">Option 2</option>
      </Select>
    </Control>
  </Field>

  <Field label="With Icons">
    <Control hasIconsLeft iconLeft={{ name: 'person' }}>
      <Select>
        <option value="huck">Huckleberry Finn</option>
        <option value="tom">Tom Sawyer</option>
      </Select>
    </Control>
  </Field>

  <Field label="Loading">
    <Control isLoading>
      <Select isLoading>
        <option value="">Please select</option>
        <option value="option1">Option 1</option>
        <option value="option2">Option 2</option>
      </Select>
    </Control>
  </Field>
</>
```

---

### With TextArea

The `Field` component can also be used with a `TextArea`. This example shows a basic usage with a label.

```tsx live
<Field label="Default">
  <Control>
    <TextArea placeholder="Carpe Diem" />
  </Control>
</Field>
```

---

### With TextArea (Rows, Colors, Sizes, States, Loading, Fixed Size)

This example demonstrates the versatility of the `TextArea` component used within a `Field`. It showcases various props like `rows`, `color`, `size`, and states like `loading`.

```tsx live
<>
  <Field label="Rows">
    <Control>
      <TextArea rows={8} placeholder="8 rows" />
    </Control>
  </Field>

  <Field label="Primary">
    <Control>
      <TextArea color="primary" placeholder="Primary (color='primary')" />
    </Control>
  </Field>

  <Field label="Small">
    <Control>
      <TextArea size="small" placeholder="Small" />
    </Control>
  </Field>

  <Field label="Hover">
    <Control>
      <TextArea isHovered placeholder="Hovered state" />
    </Control>
  </Field>

  <Field label="Loading">
    <Control isLoading>
      <TextArea placeholder="Loading state" />
    </Control>
  </Field>

  <Field label="Fixed Size">
    <Control>
      <TextArea hasFixedSize placeholder="Fixed size textarea" rows={3} />
    </Control>
  </Field>
</>
```

---

### Grouped Controls

This example demonstrates using the `Field` component to create a group of controls. The `grouped` prop is used on the `Field`, and each control is placed inside a `Control` component.

```tsx live
<Field grouped>
  <Control>
    <Input placeholder="First" />
  </Control>
  <Control>
    <Input placeholder="Second" />
  </Control>
</Field>
```

---

## Accessibility

- Uses `<label>` for accessible field labeling.
- Grouped/horizontal layouts use Bulma’s grid for layout.
- Always use the `label` prop or a custom label for clarity.

---

## Related Components

- [`Control`](./control.md): For wrapping form controls.
- [`Input`](./input.md), [`Select`](./select.md), [`TextArea`](./textarea.md): Use inside `Field`.
- [`Checkbox`](./checkbox.md), [`Checkboxes`](./checkboxes.md), [`Radio`](./radio.md), [`Radios`](./radios.md), [`File`](./file.md)

---

## Additional Resources

- [Bulma Field Documentation](https://bulma.io/documentation/form/general/#field)
- [Storybook: Field Stories](https://bestax.io/storybook/?path=/story/form-input--default)

---

## File


## Overview

The `File` component provides a Bulma-styled file input, supporting color, size, boxed/fullwidth/align styles, icons, "has name", and filename display. It is highly customizable for all file upload UI needs.

---

## Import

```tsx

```

---

## Props

| Prop             | Type                                                      | Description                                                 |
| ---------------- | --------------------------------------------------------- | ----------------------------------------------------------- |
| `color`          | `'primary' \| 'link' \| ... \| 'white'`                   | Bulma color modifier for the file input.                    |
| `size`           | `'small' \| 'medium' \| 'large'`                          | Size modifier for the file input.                           |
| `isBoxed`        | `boolean`                                                 | Boxed file input.                                           |
| `isFullwidth`    | `boolean`                                                 | File input expands to full width.                           |
| `isRight`        | `boolean`                                                 | Position the CTA on the right (with `hasName`).             |
| `isCentered`     | `boolean`                                                 | Center the file input within its container.                 |
| `hasName`        | `boolean`                                                 | Show a file name indicator.                                 |
| `buttonLabel`    | `React.ReactNode`                                         | Text on the file CTA button (defaults to "Choose a file…"). |
| `label`          | `React.ReactNode`                                         | Field label rendered above the widget.                      |
| `iconLeft`       | `React.ReactNode`                                         | Left icon element.                                          |
| `iconRight`      | `React.ReactNode`                                         | Right icon element.                                         |
| `className`      | `string`                                                  | Additional CSS classes.                                     |
| `inputClassName` | `string`                                                  | Additional CSS classes for the `<input>`.                   |
| `fileName`       | `string`                                                  | File name to display.                                       |
| ...              | All standard `<input type="file">` and Bulma helper props | (See [Helper Props](../helpers/usebulmaclasses))            |

---

## Usage

`File` is a self-contained Bulma file widget. It detects whether it's already inside a `Field` and skips rendering its own field wrapper if so. For typical use, pass `buttonLabel`, `iconLeft`, and any modifier props (`hasName`, `isBoxed`, `isFullwidth`, `isRight`, `isCentered`, `color`, `size`) — Bulma doesn't document file inputs in addons or grouped layouts, so the convenience form covers every case. Use `label` only when you want an additional Bulma `<label class="label">` rendered above the widget.

### Default

A basic file input. The `buttonLabel` prop sets the text on the CTA button, and `iconLeft` adds an icon for visual context.

```tsx live
<File buttonLabel="Choose a file…" iconLeft={<Icon name="upload" />} />
```

---

### With Filename Display

Set `hasName` to display the selected file name. The `fileName` prop shows a custom or pre-selected name.

```tsx live
<File
  hasName
  fileName="resume.pdf"
  buttonLabel="Choose a file…"
  iconLeft={<Icon name="upload" />}
/>
```

---

### CTA on Right

Combine `isRight` with `hasName` to put the CTA button on the right and the filename on the left.

```tsx live
<File
  hasName
  isRight
  fileName="contract.pdf"
  buttonLabel="Choose a file…"
  iconLeft={<Icon name="upload" />}
/>
```

---

### Full Width

`isFullwidth` makes the file input take the full width of its container — pairs well with `hasName` so the filename area expands.

```tsx live
<File
  hasName
  isFullwidth
  fileName="picture.png"
  buttonLabel="Choose a file…"
  iconLeft={<Icon name="upload" />}
/>
```

---

### Boxed

`isBoxed` stacks the icon over the text into a square box.

```tsx live
<File isBoxed buttonLabel="Choose a file…" iconLeft={<Icon name="upload" />} />
```

---

### Boxed with Name

Combine `isBoxed` and `hasName` for a boxed widget that also shows the filename.

```tsx live
<File
  isBoxed
  hasName
  fileName="holiday.jpg"
  buttonLabel="Choose a file…"
  iconLeft={<Icon name="upload" />}
/>
```

---

### Colors

The `color` prop applies Bulma color modifiers. The four examples below match the combinations Bulma's docs show.

```tsx live
<>
  <File
    color="primary"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
  <File
    color="info"
    hasName
    fileName="resume.pdf"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
  <File
    color="warning"
    isBoxed
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="cloud-upload-alt" />}
  />
  <File
    color="danger"
    isBoxed
    hasName
    fileName="resume.pdf"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="cloud-upload-alt" />}
  />
</>
```

---

### Sizes

The `size` prop controls the file input's size.

```tsx live
<>
  <File
    size="small"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
  <File buttonLabel="Choose a file…" iconLeft={<Icon name="upload" />} />
  <File
    size="medium"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
  <File
    size="large"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
</>
```

---

### Sizes with Name

Combine `size` with `hasName` to scale the filename display alongside the button.

```tsx live
<>
  <File
    size="small"
    hasName
    fileName="sample.txt"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
  <File
    hasName
    fileName="sample.txt"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
  <File
    size="medium"
    hasName
    fileName="sample.txt"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
  <File
    size="large"
    hasName
    fileName="sample.txt"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
</>
```

---

### Sizes with Boxed

Combine `size` with `isBoxed` for boxed file inputs at every size.

```tsx live
<>
  <File
    size="small"
    isBoxed
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
  <File
    isBoxed
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
  <File
    size="medium"
    isBoxed
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
  <File
    size="large"
    isBoxed
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
</>
```

---

### Sizes with Boxed and Name

For a boxed file input that also shows the filename, combine `isBoxed`, `hasName`, and `size`.

```tsx live
<>
  <File
    size="small"
    isBoxed
    hasName
    fileName="summary.docx"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
  <File
    isBoxed
    hasName
    fileName="summary.docx"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
  <File
    size="medium"
    isBoxed
    hasName
    fileName="summary.docx"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
  <File
    size="large"
    isBoxed
    hasName
    fileName="summary.docx"
    buttonLabel="Choose a file…"
    iconLeft={<Icon name="upload" />}
  />
</>
```

---

### Alignment: Centered

`isCentered` centers the widget within its parent container.

```tsx live
<File
  color="info"
  isCentered
  isBoxed
  hasName
  fileName="centered.pdf"
  buttonLabel="Choose a file…"
  iconLeft={<Icon name="upload" />}
/>
```

---

### Alignment: Right

`isRight` aligns the widget to the right of its parent.

```tsx live
<File
  color="primary"
  isRight
  hasName
  fileName="right.pdf"
  buttonLabel="Choose a file…"
  iconLeft={<Icon name="upload" />}
/>
```

---

### Context-Aware Rendering

The `File` component is context-aware: it detects whether it is already inside a `Field` and skips rendering its own field wrapper if so. Use `label` to add a Bulma `<label class="label">` above the widget; use `buttonLabel` to set the CTA text.

:::note
File does not consume the Control context (it is its own self-contained widget). The "With Field and Control Wrappers" example below shows that wrapping File in a Control is harmless but doesn't change its rendering.
:::

#### Default (with label)

The simplest usage — `label` adds a Field label above the widget.

```tsx live
<File
  label="Document"
  buttonLabel="Choose a file…"
  iconLeft={<Icon name="upload" />}
/>
```

---

#### With Field Wrapper

For manual layout control (e.g., horizontal forms), wrap in `Field`. The component detects it's inside a Field and skips rendering its own.

```tsx live
function example() {
  return (
    <Field horizontal label="Document">
      <Field.Body>
        <Field>
          <File
            buttonLabel="Choose a file…"
            iconLeft={<Icon name="upload" />}
          />
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

For full manual composition, wrap in both `Field` and `Control`. File doesn't consume Control's context but the outer Field is still detected and File's own Field wrapper is skipped.

```tsx live
function example() {
  return (
    <Field horizontal label="Document">
      <Field.Body>
        <Field>
          <Control iconLeftName="paperclip">
            <File
              buttonLabel="Choose a file…"
              iconLeft={<Icon name="upload" />}
            />
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

## Accessibility

- The root is a `` with a nested `<label>` and `<input type="file">`.
- The label is always clickable.
- Add `aria-label` to the `<input>` for accessibility if your label is not plain text.

---

## Related Components

- [`Field`](./field.md): For labeled/grouped fields.
- [`Icon`](../elements/icon.md): For file icons.
- [Helper Props](../helpers/usebulmaclasses.md)

---

## Additional Resources

- [Bulma File Documentation](https://bulma.io/documentation/form/file/)
- [Storybook: File Stories](https://bestax.io/storybook/?path=/story/form-file--default)

---

## Input


## Overview

The `Input` component provides a Bulma-styled text input, supporting colors, sizes, rounded corners, static/read-only state, hover/focus/loading states, and all Bulma helper props. It is suitable for all standard text input types.

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                          | Description                                      |
| ----------- | --------------------------------------------- | ------------------------------------------------ |
| `color`     | `'primary' \| 'link' \| ... \| 'white'`       | Bulma color modifier.                            |
| `size`      | `'small' \| 'medium' \| 'large'`              | Size modifier.                                   |
| `isRounded` | `boolean`                                     | Rounded input corners.                           |
| `isStatic`  | `boolean`                                     | Renders input as static (read only, styled).     |
| `isHovered` | `boolean`                                     | Applies hovered state.                           |
| `isFocused` | `boolean`                                     | Applies focused state.                           |
| `isLoading` | `boolean`                                     | Shows loading indicator.                         |
| `className` | `string`                                      | Additional CSS classes.                          |
| `disabled`  | `boolean`                                     | Disabled input.                                  |
| `readOnly`  | `boolean`                                     | Read-only input.                                 |
| ...         | All standard `<input>` and Bulma helper props | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

`Input` is a convenience component that internally composes `Field` and `Control`. For most form fields, use `<Input>` directly with its props (`label`, `color`, `size`, `iconLeftName`, `message`, `horizontal`, etc.). Reach for explicit `<Field>` + `<Control>` composition only when you need a layout the convenience props can't express — most commonly **form addons**, **grouped controls**, or **horizontal layouts that mix multiple sub-fields**.

### Default Input

A standard text input. The `placeholder` prop provides hint text for the user.

```tsx live
<Input label="Default" placeholder="Default input" />
```

---

### Color Inputs

The `color` prop applies Bulma color modifiers to the input. Use it to visually distinguish input fields based on context or validation state.

```tsx live
<>
  <Input label="Primary" color="primary" placeholder="Primary input" />
  <Input label="Link" color="link" placeholder="Link input" />
  <Input label="Info" color="info" placeholder="Info input" />
  <Input label="Success" color="success" placeholder="Success input" />
  <Input label="Warning" color="warning" placeholder="Warning input" />
  <Input label="Danger" color="danger" placeholder="Danger input" />
</>
```

---

### Sizes

The `size` prop controls the input's size. Options: `"small"`, `"medium"`, `"large"` (default is normal).

```tsx live
<>
  <Input label="Small" size="small" placeholder="Small input" />
  <Input label="Normal" placeholder="Normal input" />
  <Input label="Medium" size="medium" placeholder="Medium input" />
  <Input label="Large" size="large" placeholder="Large input" />
</>
```

---

### Style: Rounded

The `isRounded` prop gives the input rounded corners for a softer appearance.

```tsx live
<Input label="Rounded" isRounded placeholder="Rounded input" />
```

---

### States

`isHovered`, `isFocused`, and `isLoading` force the corresponding state on the input.

```tsx live
<>
  <Input label="Normal" placeholder="Normal state" />
  <Input label="Hover" isHovered placeholder="Hovered state" />
  <Input label="Focus" isFocused placeholder="Focused state" />
  <Input label="Loading" isLoading placeholder="Loading state" />
</>
```

---

### Loading States by Size

The loading indicator at every input size. Use `controlSize` on `<Input>` to scale the spinner to match.

```tsx live
<>
  <Input
    label="Loading Small"
    size="small"
    controlSize="small"
    isLoading
    placeholder="Loading small"
  />
  <Input label="Loading Normal" isLoading placeholder="Loading normal" />
  <Input
    label="Loading Medium"
    size="medium"
    controlSize="medium"
    isLoading
    placeholder="Loading medium"
  />
  <Input
    label="Loading Large"
    size="large"
    controlSize="large"
    isLoading
    placeholder="Loading large"
  />
</>
```

---

### Disabled & Read Only

Disabled inputs cannot be interacted with; read-only inputs can be focused but not edited.

```tsx live
<>
  <Input label="Disabled" disabled placeholder="Disabled input" />
  <Input label="Read Only" readOnly value="Read only value" />
</>
```

---

### Static State

The `isStatic` prop renders the input as non-interactive text — useful for displaying read-only values alongside editable fields.

```tsx live
<>
  <Input horizontal label="Username" isStatic value="Static value" />
  <Input horizontal label="Password" placeholder="Editable value" />
</>
```

---

### With Icons (Left and Right)

Add icons via the `iconLeftName` / `iconRightName` shortcuts on `<Input>`.

```tsx live
<>
  <Input iconLeftName="user" iconRightName="check" placeholder="With icons" />
  <Input
    iconLeftName="envelope"
    iconRightName="exclamation-triangle"
    placeholder="Another input"
  />
</>
```

---

### With Icons and Size Variations

Match the input size to the icon size via the `size` + `iconLeftSize` / `iconRightSize` props.

```tsx live
<>
  <Input
    size="small"
    iconLeftName="user"
    iconLeftSize="small"
    iconRightName="check"
    iconRightSize="small"
    placeholder="Icons left/right small"
  />
  <Input
    iconLeftName="user"
    iconRightName="check"
    placeholder="Icons left/right normal"
  />
  <Input
    size="medium"
    iconLeftName="user"
    iconLeftSize="medium"
    iconRightName="check"
    iconRightSize="medium"
    placeholder="Icons left/right medium"
  />
  <Input
    size="large"
    iconLeftName="user"
    iconLeftSize="large"
    iconRightName="check"
    iconRightSize="large"
    placeholder="Icons left/right large"
  />
</>
```

---

### Help Text Colors

Pair `color` and `messageColor` to produce success and danger validation states with matching help text.

```tsx live
<>
  <Input
    label="Username"
    color="success"
    value="bulma"
    message="This username is available"
    messageColor="success"
    iconLeftName="user"
    iconRightName="check"
    onChange={() => {}}
  />
  <Input
    label="Email"
    type="email"
    color="danger"
    value="hello@"
    message="This email is invalid"
    messageColor="danger"
    iconLeftName="envelope"
    iconRightName="exclamation-triangle"
    onChange={() => {}}
  />
</>
```

---

### Form Addons

For multi-control rows like input + button, drop down to manual `Field` + `Control` composition. Use `<Field hasAddons>` with multiple `<Control>` children. Use `<Control isExpanded>` on the input so it fills the available space.

#### Input + Button

```tsx live
<Field hasAddons>
  <Control isExpanded>
    <Input placeholder="Find a repository" />
  </Control>
  <Control>
    <Button color="info">Search</Button>
  </Control>
</Field>
```

#### Input + Static Suffix

A static button is non-interactive — useful for fixed prefixes/suffixes such as an email domain.

```tsx live
<Field hasAddons>
  <Control isExpanded>
    <Input placeholder="Your email" />
  </Control>
  <Control>
    <Button isStatic>@gmail.com</Button>
  </Control>
</Field>
```

#### Select + Input + Button

```tsx live
<Field hasAddons>
  <Control>
    <Select aria-label="Country code">
      <option>+1</option>
      <option>+44</option>
      <option>+33</option>
    </Select>
  </Control>
  <Control isExpanded>
    <Input type="tel" placeholder="Your phone number" />
  </Control>
  <Control>
    <Button color="primary">Call</Button>
  </Control>
</Field>
```

#### Centered Addons

Pass `hasAddons="centered"` to center the addon group on the row.

```tsx live
<Field hasAddons="centered">
  <Control>
    <Button>Yes</Button>
  </Control>
  <Control>
    <Button>Maybe</Button>
  </Control>
  <Control>
    <Button>No</Button>
  </Control>
</Field>
```

#### Right-Aligned Addons

Pass `hasAddons="right"` to right-align the group.

```tsx live
<Field hasAddons="right">
  <Control>
    <Button>Yes</Button>
  </Control>
  <Control>
    <Button>Maybe</Button>
  </Control>
  <Control>
    <Button>No</Button>
  </Control>
</Field>
```

---

### Form Group

Use `<Field grouped>` to lay multiple controls out on a single row with consistent spacing — common for form action buttons and search-style rows.

#### Grouped Buttons

```tsx live
<Field grouped>
  <Control>
    <Button color="link">Submit</Button>
  </Control>
  <Control>
    <Button>Cancel</Button>
  </Control>
</Field>
```

#### Centered Group

```tsx live
<Field grouped="centered">
  <Control>
    <Button color="link">Submit</Button>
  </Control>
  <Control>
    <Button>Cancel</Button>
  </Control>
</Field>
```

#### Right-Aligned Group

```tsx live
<Field grouped="right">
  <Control>
    <Button color="link">Submit</Button>
  </Control>
  <Control>
    <Button>Cancel</Button>
  </Control>
</Field>
```

#### Expanded Input + Button

```tsx live
<Field grouped>
  <Control isExpanded>
    <Input placeholder="Find a repository" />
  </Control>
  <Control>
    <Button color="info">Search</Button>
  </Control>
</Field>
```

#### Multiline Group

`grouped="multiline"` allows the row to wrap onto multiple lines.

```tsx live
<Field grouped="multiline">
  {[
    'One',
    'Two',
    'Three',
    'Four',
    'Five',
    'Six',
    'Seven',
    'Eight',
    'Nine',
    'Ten',
    'Eleven',
    'Twelve',
    'Thirteen',
  ].map(label => (
    <Control key={label}>
      <Button>{label}</Button>
    </Control>
  ))}
</Field>
```

---

### Horizontal — Validation Error

Place a `color="danger"` Input and a danger help message inside the horizontal field body.

```tsx live
<Field horizontal label="Email">
  <Field.Body>
    <Field>
      <Control iconLeftName="envelope" iconRightName="exclamation-triangle">
        <Input type="email" color="danger" value="hello@" onChange={() => {}} />
      </Control>
      This email is invalid
    </Field>
  </Field.Body>
</Field>
```

---

### Horizontal — Addons (Phone with Country Code)

Combine `Field horizontal` with a nested `Field hasAddons` inside the body to mix layouts.

```tsx live
<Field horizontal label="Phone">
  <Field.Body>
    <Field hasAddons>
      <Control>
        <Button isStatic>+44</Button>
      </Control>
      <Control isExpanded>
        <Input type="tel" placeholder="Your phone number" />
      </Control>
    </Field>
  </Field.Body>
</Field>
```

---

### Horizontal — Submit Row

Use an empty `Field.Label` to align the submit button under the inputs above it.

```tsx live
<>
  <Field horizontal label="Name">
    <Field.Body>
      <Field>
        <Control>
          <Input placeholder="Your name" />
        </Control>
      </Field>
    </Field.Body>
  </Field>
  <Field horizontal>
    <Field.Label />
    <Field.Body>
      <Field>
        <Control>
          <Button color="primary">Submit</Button>
        </Control>
      </Field>
    </Field.Body>
  </Field>
</>
```

---

### Disabled Fieldset

Wrap multiple Inputs in a native `<fieldset disabled>` to disable every field at once.

```tsx live
<fieldset disabled>
  <Input label="Name" placeholder="Your name" />
  <Input label="Email" type="email" placeholder="Your email" />
</fieldset>
```

---

### Context-Aware Rendering

The `Input` component is context-aware: it detects whether it is already inside a `Field` or `Control` and adjusts its rendering accordingly. This means you can use it standalone with a `label` prop (it wraps itself in Field+Control), inside a `Field` (it skips its own Field), or inside both `Field` and `Control` (it renders only the raw input).

#### Default (with label)

The simplest usage — the component automatically renders its own Field and Control wrappers.

```tsx live
<Input label="Username" placeholder="Enter username" />
```

---

#### With Field Wrapper

When you need manual control over the Field layout (e.g., horizontal forms), wrap the component in `Field`. The component detects it's inside a Field and skips rendering its own.

```tsx live
function example() {
  return (
    <Field horizontal label="Username">
      <Field.Body>
        <Field>
          <Input placeholder="Enter username" />
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

For full manual control (e.g., adding icons via Control), wrap in both Field and Control. The component detects both and renders only its raw element.

```tsx live
function example() {
  return (
    <Field horizontal label="Username">
      <Field.Body>
        <Field>
          <Control iconLeftName="user">
            <Input placeholder="Enter username" />
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

## Accessibility

- Always provide a `<label>` (use with `Field`) for accessible input usage.
- Use the correct input `type` for semantics (`text`, `email`, etc.).

---

## Related Components

- [`Control`](./control.md): For icons and loading.
- [`Field`](./field.md): For field grouping and labels.

---

## Additional Resources

- [Bulma Input Documentation](https://bulma.io/documentation/form/input/)
- [Storybook: Input Stories](https://bestax.io/storybook/?path=/story/form-input--default)

---

## Numberinput


## Overview

The `Numberinput` component provides a number input with increment/decrement buttons. It's ideal for quantity selectors, step inputs, and any numeric value that benefits from easy +/- adjustment.

---

## Import

```tsx

```

---

## Props

| Prop               | Type                                                                                                     | Default       | Description                                               |
| ------------------ | -------------------------------------------------------------------------------------------------------- | ------------- | --------------------------------------------------------- |
| `value`            | `number`                                                                                                 | —             | Controlled value.                                         |
| `defaultValue`     | `number`                                                                                                 | —             | Default value for uncontrolled usage.                     |
| `min`              | `number`                                                                                                 | —             | Minimum allowed value.                                    |
| `max`              | `number`                                                                                                 | —             | Maximum allowed value.                                    |
| `step`             | `number`                                                                                                 | `1`           | Step increment.                                           |
| `size`             | `'small'` \| `'medium'` \| `'large'`                                                                     | —             | Size variant.                                             |
| `color`            | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'light'` \| `'dark'` | —             | Color variant for buttons.                                |
| `controlsPosition` | `'left'` \| `'right'` \| `'both'`                                                                        | `'both'`      | Position of +/- buttons.                                  |
| `controlsRounded`  | `boolean`                                                                                                | `false`       | Use rounded buttons.                                      |
| `disabled`         | `boolean`                                                                                                | `false`       | Whether the input is disabled.                            |
| `editable`         | `boolean`                                                                                                | `true`        | Whether the input can be typed in.                        |
| `onChange`         | `(value: number) => void`                                                                                | —             | Callback when value changes.                              |
| `inputColor`       | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`                          | —             | Color of the input field itself.                          |
| `compact`          | `boolean`                                                                                                | `false`       | Uses compact button spacing.                              |
| `bare`             | `boolean`                                                                                                | `false`       | Removes button borders and background.                    |
| `variant`          | `'plusminus'` \| `'stepper'`                                                                             | `'plusminus'` | Style variant for the control buttons.                    |
| `isLoading`        | `boolean`                                                                                                | `false`       | Shows a loading state.                                    |
| `exponential`      | `boolean`                                                                                                | `false`       | Enables exponential step increments when holding buttons. |
| `className`        | `string`                                                                                                 | —             | Additional CSS classes.                                   |
| `ref`              | `React.Ref<HTMLElement>`                                                                                 | —             | Ref forwarded to the input element.                       |
| ...                | All standard HTML and Bulma helper props                                                                 |               | (See [Helper Props](../helpers/usebulmaclasses))          |

---

## Usage

### Basic Numberinput

A simple number input with +/- buttons.

```tsx live
function example() {
  const [value, setValue] = useState(5);
  return (
    <Block>
      <Numberinput value={value} onChange={setValue} />
      <Paragraph mt="2">Value: {value}</Paragraph>
    </Block>
  );
}
```

---

### With Min and Max

Number input with value constraints.

```tsx live
function example() {
  const [quantity, setQuantity] = useState(1);
  return (
    <Block>
      <Paragraph mb="2">Quantity (1-10):</Paragraph>
      <Numberinput
        value={quantity}
        onChange={setQuantity}
        min={1}
        max={10}
        color="primary"
      />
    </Block>
  );
}
```

---

### Color Variants

Number inputs with different button colors.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <Numberinput defaultValue={5} color="primary" />
  <Numberinput defaultValue={5} color="success" />
  <Numberinput defaultValue={5} color="info" />
  <Numberinput defaultValue={5} color="warning" />
  <Numberinput defaultValue={5} color="danger" />
</Block>
```

---

### Size Variants

Number inputs in different sizes.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <Numberinput defaultValue={5} size="small" color="primary" />
  <Numberinput defaultValue={5} color="primary" />
  <Numberinput defaultValue={5} size="medium" color="primary" />
  <Numberinput defaultValue={5} size="large" color="primary" />
</Block>
```

---

### Controls Position

Different positions for the +/- buttons.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <Block>
    <Paragraph mb="1">Both sides (default)</Paragraph>
    <Numberinput defaultValue={5} controlsPosition="both" color="primary" />
  </Block>
  <Block>
    <Paragraph mb="1">Left only</Paragraph>
    <Numberinput defaultValue={5} controlsPosition="left" color="info" />
  </Block>
  <Block>
    <Paragraph mb="1">Right only</Paragraph>
    <Numberinput defaultValue={5} controlsPosition="right" color="success" />
  </Block>
</Block>
```

---

### Rounded Buttons

Number input with rounded +/- buttons.

```tsx live
<Numberinput defaultValue={5} controlsRounded color="primary" />
```

---

### Custom Step

Number input with custom step increment.

```tsx live
function example() {
  const [value, setValue] = useState(0);
  return (
    <Block>
      <Paragraph mb="2">Step by 10:</Paragraph>
      <Numberinput
        value={value}
        onChange={setValue}
        step={10}
        min={0}
        max={100}
        color="info"
      />
      <Paragraph mt="2">Value: {value}</Paragraph>
    </Block>
  );
}
```

---

### Read-only Input

Number input where you can only use the buttons (not type directly).

```tsx live
<Numberinput defaultValue={5} editable={false} color="primary" />
```

---

### Disabled State

A disabled number input.

```tsx live
<Numberinput defaultValue={5} disabled />
```

---

### Context-Aware Rendering

The `Numberinput` component is context-aware: it detects whether it is already inside a `Field` and adjusts its rendering accordingly. This means you can use it standalone with a `label` prop (it wraps itself in a Field), or inside a `Field` (it skips rendering its own).

:::note
Numberinput does not use ControlContext, so the "With Field and Control Wrappers" example below uses Field wrapping only. The Control wrapper is shown for layout consistency but does not change the component's internal rendering.
:::

#### Default (with label)

The simplest usage — the component automatically renders its own Field wrapper.

```tsx live
<Numberinput
  label="Quantity"
  defaultValue={1}
  min={1}
  max={10}
  color="primary"
/>
```

---

#### With Field Wrapper

When you need manual control over the Field layout (e.g., horizontal forms), wrap the component in `Field`. The component detects it's inside a Field and skips rendering its own.

```tsx live
function example() {
  return (
    <Field horizontal label="Quantity">
      <Field.Body>
        <Field>
          <Numberinput defaultValue={1} min={1} max={10} color="primary" />
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

For full manual composition, wrap in both Field and Control. Numberinput does not consume ControlContext, but the Field wrapper is still detected and its own Field is skipped.

```tsx live
function example() {
  return (
    <Field horizontal label="Quantity">
      <Field.Body>
        <Field>
          <Control iconLeftName="hashtag">
            <Numberinput defaultValue={1} min={1} max={10} color="primary" />
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

## Controlled vs Uncontrolled

### Controlled Mode

Use `value` and `onChange` to manage state externally:

```tsx
const [quantity, setQuantity] = useState(1);
<Numberinput value={quantity} onChange={setQuantity} min={1} max={10} />;
```

### Uncontrolled Mode

Use `defaultValue` for internal state management:

```tsx
<Numberinput defaultValue={5} min={0} max={100} />
```

---

## Accessibility

- Uses native number input element
- Has `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` attributes
- +/- buttons have `aria-label` for screen readers
- Arrow keys increment/decrement the value
- Buttons are disabled at min/max boundaries

---

## Related Components

- [Slider](./slider.md) - For selecting values with a range slider
- [Input](./input.md) - For general text/number input

---

## Additional Resources

- [Storybook: Numberinput Stories](https://bestax.io/storybook/?path=/story/form-numberinput)

:::tip Pro Tip
Set `editable={false}` when you want users to only use the +/- buttons, preventing manual typing errors.
:::

---

## Radio


## Overview

The `Radio` component provides a Bulma-styled radio button input with flexible labels and helper classes. Use it for mutually exclusive choices in forms—either standalone or grouped (with the same `name`).

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `disabled`  | `boolean`                                                                                                                                                                                                                                                                                | Whether the radio is disabled.                   |
| `color`     | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`                                                                                                                                                                                                          | Color of the radio button.                       |
| `size`      | `'small'` \| `'normal'` \| `'medium'` \| `'large'`                                                                                                                                                                                                                                       | Size of the radio button.                        |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | Text color helper.                               |
| `className` | `string`                                                                                                                                                                                                                                                                                 | Additional CSS classes.                          |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | Label/content for the radio.                     |
| ...         | All standard `<input type="radio">` and Bulma helper props                                                                                                                                                                                                                               | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Mutually Exclusive Radios (Only One Can Be Selected)

This example shows how to use the `Radio` component for mutually exclusive choices. Assign the same `name` prop to each `Radio` in a group to ensure only one can be selected at a time. Use within a `Control` for proper Bulma styling.

```tsx live
<Control>
  <Radio name="mutuallyExclusive"> Yes </Radio>
  <Radio name="mutuallyExclusive"> No </Radio>
  <Radio name="mutuallyExclusive"> Maybe </Radio>
</Control>
```

---

### Default Selected Radio

Set the `defaultChecked` prop on a `Radio` to make it selected by default. This is useful for pre-selecting a common or recommended option in a group.

```tsx live
<Control>
  <Radio name="pet"> Cat </Radio>
  <Radio name="pet" defaultChecked>
    {' '}
    Dog{' '}
  </Radio>
</Control>
```

---

### Disabled Radios

Use the `disabled` prop to render radios that cannot be selected. This is helpful for indicating unavailable options in a group.

```tsx live
<Control>
  <Radio name="response" disabled>
    {' '}
    Attend{' '}
  </Radio>
  <Radio name="response" disabled>
    {' '}
    Decline{' '}
  </Radio>
  <Radio name="response" disabled>
    {' '}
    Tentative{' '}
  </Radio>
</Control>
```

---

### List of Radios (Grouped with the `Radios` Wrapper)

Render a list of radios using the `Radios` wrapper component. This is useful for grouping related radio buttons together, especially when they share the same `name` prop. In this example, all radios are disabled.

```tsx live
<Radios>
  <Radio name="event" disabled>
    {' '}
    Attend{' '}
  </Radio>
  <Radio name="event" disabled>
    {' '}
    Decline{' '}
  </Radio>
  <Radio name="event" disabled>
    {' '}
    Tentative{' '}
  </Radio>
</Radios>
```

---

## Accessibility

- Each `Radio` is rendered as a `<label>` wrapping an `<input type="radio">` and the label text, for optimal accessibility.
- Use the same `name` prop for a group of radios to ensure only one can be selected.

---

## Related Components

- [`Radios`](./radios.md): For grouped radio buttons.
- [`Field`](./field.md): For labeled/grouped form fields.
- [Helper Props](../helpers/usebulmaclasses.md)

---

## Additional Resources

- [Bulma Radio Documentation](https://bulma.io/documentation/form/radio/)
- [Storybook: Radio Stories](https://bestax.io/storybook/?path=/story/form-radio--mutuallyexclusive)

---

## Radios


## Overview

The `Radios` component wraps multiple `Radio` components in a Bulma-styled group. Use it for lists of mutually exclusive choices, such as RSVP or selection lists.

---

## Import

```tsx

```

---

## Props

| Prop           | Type                      | Description                                                       |
| -------------- | ------------------------- | ----------------------------------------------------------------- |
| `name`         | `string`                  | Form field name shared by every Radio in the group (via context). |
| `value`        | `string`                  | Currently-selected value (controlled mode).                       |
| `defaultValue` | `string`                  | Initial selected value (uncontrolled mode).                       |
| `onChange`     | `(value: string) => void` | Fires when the selection changes.                                 |
| `className`    | `string`                  | Additional CSS classes.                                           |
| `children`     | `React.ReactNode`         | Radio elements to render in the group.                            |
| ...            | All Bulma helper props    | (See [Helper Props](../helpers/usebulmaclasses))                  |

---

## Usage

### Grouped Radios (All Disabled Example)

This example demonstrates the `Radios` component wrapping multiple `Radio` children, all with the same `name` prop for mutual exclusivity. The `disabled` prop is set on each `Radio` to render them as non-interactive. Use this pattern for lists of mutually exclusive options, such as RSVP or selection lists.

```tsx live
<Radios>
  <Radio name="event" disabled>
    {' '}
    Attend{' '}
  </Radio>
  <Radio name="event" disabled>
    {' '}
    Decline{' '}
  </Radio>
  <Radio name="event" disabled>
    {' '}
    Tentative{' '}
  </Radio>
</Radios>
```

---

### Context-Aware Rendering

The `Radios` component is context-aware: it detects whether it is already inside a `Field` or `Control` and adjusts its rendering accordingly. This means you can use it standalone with a `label` prop (it wraps itself in Field+Control), inside a `Field` (it skips its own Field), or inside both `Field` and `Control` (it renders only the raw radio group).

#### Default (with label)

The simplest usage — the component automatically renders its own Field and Control wrappers.

```tsx live
<Radios label="RSVP">
  <Radio name="rsvp"> Attend </Radio>
  <Radio name="rsvp"> Decline </Radio>
  <Radio name="rsvp"> Tentative </Radio>
</Radios>
```

---

#### With Field Wrapper

When you need manual control over the Field layout (e.g., horizontal forms), wrap the component in `Field`. The component detects it's inside a Field and skips rendering its own.

```tsx live
function example() {
  return (
    <Field horizontal label="RSVP">
      <Field.Body>
        <Field>
          <Radios>
            <Radio name="rsvp2"> Attend </Radio>
            <Radio name="rsvp2"> Decline </Radio>
            <Radio name="rsvp2"> Tentative </Radio>
          </Radios>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

For full manual control, wrap in both Field and Control. The component detects both and renders only the raw radio group.

```tsx live
function example() {
  return (
    <Field horizontal label="RSVP">
      <Field.Body>
        <Field>
          <Control>
            <Radios>
              <Radio name="rsvp3"> Attend </Radio>
              <Radio name="rsvp3"> Decline </Radio>
              <Radio name="rsvp3"> Tentative </Radio>
            </Radios>
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

## Group State

`Radios` can manage selection state for the entire group, matching the pattern used by MUI's `RadioGroup`, Radix's `RadioGroup`, and React Aria's `RadioGroup`. Three usage modes:

1. **Name-only** — pass just `name`. Each child `Radio` manages its own checked state via `defaultChecked` or `checked`. Backwards compatible with existing usage.
2. **Controlled** — pass `value` and `onChange`. The parent owns selection; each `Radio` derives `checked` from `group.value === my.value`.
3. **Uncontrolled** — pass `defaultValue` (and optionally `onChange`). The group manages internal state; `onChange` fires on selection change.

Local props (`checked`, `onChange`) on individual `Radio` children always win over the group context — useful for opt-out scenarios.

### Controlled

```tsx live
function ControlledRadios() {
  const [color, setColor] = React.useState('red');
  return (
    
      <Radios name="color" value={color} onChange={setColor}>
        <Radio value="red">Red</Radio>
        <Radio value="green">Green</Radio>
        <Radio value="blue">Blue</Radio>
      </Radios>
      
        Selected: {color}
      
    
  );
}
```

### Uncontrolled

```tsx live
function UncontrolledRadios() {
  const [last, setLast] = React.useState('');
  return (
    
      <Radios name="size" defaultValue="md" onChange={setLast}>
        <Radio value="sm">Small</Radio>
        <Radio value="md">Medium</Radio>
        <Radio value="lg">Large</Radio>
      </Radios>
      {last && (
        
          Last selected: {last}
        
      )}
    
  );
}
```

---

## Form Submission

`Radios` is HTML-form-compatible. Pass a `name` prop on the group and every child `Radio` inherits it via React context (works at any nesting depth — including custom wrapper components, fragments, and conditionals). The selected value submits as `name=value` in `FormData`, like a native radio group.

| Prop   | Description                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------- |
| `name` | Form field name shared by every child Radio. Children with their own `name` prop keep theirs (explicit > implicit). |

```tsx live
function RadiosFormDemo() {
  const [submitted, setSubmitted] = React.useState('');
  return (
    <form
      onSubmit={e => {
        e.preventDefault();
        const fd = new FormData(e.currentTarget);
        setSubmitted(JSON.stringify(Array.from(fd.entries()), null, 2));
      }}
    >
      <Radios name="color">
        <Radio value="red" defaultChecked>
          Red
        </Radio>
        <Radio value="green">Green</Radio>
        <Radio value="blue">Blue</Radio>
      </Radios>
      
        <button type="submit" className="button is-primary">
          Submit
        </button>
      
      {submitted && <pre style={{ marginTop: '1rem' }}>{submitted}</pre>}
    </form>
  );
}
```

The same `name` propagation works through any wrapper — useful for layouts like radio cards:

```tsx live
function RadiosWrappedFormDemo() {
  const [submitted, setSubmitted] = React.useState('');
  const RadioCard = ({ value, label }) => (
    
      <Radio value={value}>{label}</Radio>
    
  );
  return (
    <form
      onSubmit={e => {
        e.preventDefault();
        const fd = new FormData(e.currentTarget);
        setSubmitted(JSON.stringify(Array.from(fd.entries()), null, 2));
      }}
    >
      <Radios name="plan">
        <RadioCard value="basic" label="Basic — $9/mo" />
        <RadioCard value="pro" label="Pro — $29/mo" />
        <RadioCard value="enterprise" label="Enterprise — Contact us" />
      </Radios>
      
        <button type="submit" className="button is-primary">
          Submit
        </button>
      
      {submitted && <pre style={{ marginTop: '1rem' }}>{submitted}</pre>}
    </form>
  );
}
```

---

## Accessibility

- The group is rendered as a `` containing labeled radio buttons.
- Each child should be a `Radio` for proper labeling and accessibility.
- Use the same `name` for all radios in a group to ensure mutual exclusivity.

---

## Related Components

- [`Radio`](./radio.md): Individual radio button.
- [`Field`](./field.md): For labeled/grouped form fields.

---

## Additional Resources

- [Bulma Radios Documentation](https://bulma.io/documentation/form/radio/#grouped-radios)
- [Storybook: Radio Stories](https://bestax.io/storybook/?path=/story/form-radio--listofradios)

---

## Rate


## Overview

The `Rate` component provides a star/icon-based rating system. It supports custom icons, sizes, and display options for building rating interfaces.

---

## Import

```tsx

```

---

## Props

| Prop           | Type                                                                            | Default | Description                                      |
| -------------- | ------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `value`        | `number`                                                                        | —       | Controlled value (0 to max).                     |
| `defaultValue` | `number`                                                                        | `0`     | Default value for uncontrolled usage.            |
| `max`          | `number`                                                                        | `5`     | Maximum rating value.                            |
| `size`         | `'small'` \| `'medium'` \| `'large'`                                            | —       | Size variant.                                    |
| `disabled`     | `boolean`                                                                       | `false` | Whether the rating is disabled.                  |
| `showScore`    | `boolean`                                                                       | `false` | Show the numeric score next to stars.            |
| `showText`     | `boolean`                                                                       | `false` | Show custom text based on value.                 |
| `texts`        | `string[]`                                                                      | —       | Array of text labels for each rating value.      |
| `onChange`     | `(value: number) => void`                                                       | —       | Callback when rating changes.                    |
| `customIcon`   | `(props: RateIconProps) => React.ReactNode`                                     | —       | Custom icon renderer.                            |
| `iconName`     | `string`                                                                        | —       | Custom icon name for the rating stars.           |
| `iconLibrary`  | `'fa'` \| `'mdi'` \| `'ion'` \| `'material-icons'` \| `'material-symbols'`      | —       | Icon library to use.                             |
| `iconVariant`  | `string`                                                                        | —       | Icon style variant.                              |
| `iconFeatures` | `string` \| `string[]`                                                          | —       | Additional icon modifiers.                       |
| `color`        | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` | —       | Color of the active rating icons.                |
| `precision`    | `number`                                                                        | `1`     | Rating precision (e.g., `0.5` for half stars).   |
| `customText`   | `string`                                                                        | —       | Custom text displayed next to the rating.        |
| `spaced`       | `boolean`                                                                       | `false` | Add spacing between icons.                       |
| `rtl`          | `boolean`                                                                       | `false` | Right-to-left direction.                         |
| `className`    | `string`                                                                        | —       | Additional CSS classes.                          |
| `ref`          | `React.Ref<HTMLElement>`                                                        | —       | Ref forwarded to the container element.          |
| ...            | All standard HTML and Bulma helper props                                        |         | (See [Helper Props](../helpers/usebulmaclasses)) |

### RateIconProps

| Prop        | Type      | Description                                     |
| ----------- | --------- | ----------------------------------------------- |
| `index`     | `number`  | The index of this icon (0-based).               |
| `isActive`  | `boolean` | Whether this icon is currently active (filled). |
| `isHovered` | `boolean` | Whether this icon is currently hovered.         |
| `value`     | `number`  | The current value.                              |

---

## Usage

### Basic Rating

A simple 5-star rating.

```tsx live
function example() {
  const [rating, setRating] = useState(3);
  return (
    <Block>
      <Rate value={rating} onChange={setRating} />
      <Paragraph mt="2">Rating: {rating} stars</Paragraph>
    </Block>
  );
}
```

---

### With Score Display

Rating showing the numeric score.

```tsx live
function example() {
  const [rating, setRating] = useState(4);
  return <Rate value={rating} onChange={setRating} showScore />;
}
```

---

### With Text Labels

Rating with descriptive text for each level.

```tsx live
function example() {
  const [rating, setRating] = useState(3);
  return (
    <Rate
      value={rating}
      onChange={setRating}
      showText
      texts={['Poor', 'Fair', 'Average', 'Good', 'Excellent']}
    />
  );
}
```

---

### With Score and Text

Both score and text displayed together.

```tsx live
function example() {
  const [rating, setRating] = useState(4);
  return (
    <Rate
      value={rating}
      onChange={setRating}
      showScore
      showText
      texts={['Terrible', 'Bad', 'OK', 'Good', 'Great']}
    />
  );
}
```

---

### Size Variants

Ratings in different sizes.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <Rate defaultValue={3} size="small" />
  <Rate defaultValue={3} />
  <Rate defaultValue={3} size="medium" />
  <Rate defaultValue={3} size="large" />
</Block>
```

---

### Custom Max Value

Rating with more than 5 stars.

```tsx live
function example() {
  const [rating, setRating] = useState(7);
  return (
    <Block>
      <Rate value={rating} onChange={setRating} max={10} showScore />
      <Paragraph mt="2">Rating: {rating} out of 10</Paragraph>
    </Block>
  );
}
```

---

### Spaced Icons

Rating with spacing between stars.

```tsx live
<Rate defaultValue={3} spaced />
```

---

### Disabled Rating

A read-only rating display.

```tsx live
<Rate value={4} disabled showScore />
```

---

### Custom Icons

Rating with custom heart icons.

```tsx live
function example() {
  const [rating, setRating] = useState(3);

  const HeartIcon = ({ isActive }) => (
    <svg
      xmlns="http://www.w3.org/2000/svg"
      viewBox="0 0 24 24"
      fill={isActive ? 'currentColor' : 'none'}
      stroke="currentColor"
      strokeWidth={isActive ? 0 : 2}
      style={{ color: '#f14668' }}
    >
      <path d="M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z" />
    </svg>
  );

  return (
    <Rate
      value={rating}
      onChange={setRating}
      customIcon={({ isActive }) => <HeartIcon isActive={isActive} />}
      showScore
    />
  );
}
```

---

### Context-Aware Rendering

The `Rate` component is context-aware: it detects whether it is already inside a `Field` and adjusts its rendering accordingly. This means you can use it standalone with a `label` prop (it wraps itself in a Field), or inside a `Field` (it skips rendering its own).

#### Default (with label)

The simplest usage — the component automatically renders its own Field wrapper.

```tsx live
<Rate label="Rating" defaultValue={3} />
```

---

#### With Field Wrapper

When you need manual control over the Field layout (e.g., horizontal forms), wrap the component in `Field`. The component detects it's inside a Field and skips rendering its own.

```tsx live
function example() {
  return (
    <Field horizontal label="Rating">
      <Field.Body>
        <Field>
          <Rate defaultValue={3} />
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

For full manual composition, wrap in both Field and Control. The component detects the Field context and renders only the rating element.

```tsx live
function example() {
  return (
    <Field horizontal label="Rating">
      <Field.Body>
        <Field>
          <Control iconLeftName="star">
            <Rate defaultValue={3} />
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

## Controlled vs Uncontrolled

### Controlled Mode

Use `value` and `onChange` to manage state externally:

```tsx
const [rating, setRating] = useState(3);
<Rate value={rating} onChange={setRating} />;
```

### Uncontrolled Mode

Use `defaultValue` for internal state management:

```tsx
<Rate defaultValue={3} />
```

---

## Click Behavior

Clicking the same star twice will deselect it (set value to 0). This allows users to clear their rating if needed.

---

## Form Submission

`Rate` is an HTML form element. Pass a `name` prop and the current rating value is rendered as a hidden `<input type="hidden">` inside the component, so it's included in `FormData` on submit and posts to the server like any native input.

| Prop   | Description                                                                                               |
| ------ | --------------------------------------------------------------------------------------------------------- |
| `name` | Form field name. When set, a hidden input is rendered.                                                    |
| `form` | Optional id of the form this hidden input belongs to (use when the input lives outside the form element). |

Submit the form below and inspect the resulting `FormData` entries:

```tsx live
function RateFormDemo() {
  const [submitted, setSubmitted] = React.useState('');
  return (
    <form
      onSubmit={e => {
        e.preventDefault();
        const fd = new FormData(e.currentTarget);
        setSubmitted(JSON.stringify(Array.from(fd.entries()), null, 2));
      }}
    >
      <Rate name="rating" defaultValue={3} showScore />
      
        <button type="submit" className="button is-primary">
          Submit
        </button>
      
      {submitted && <pre style={{ marginTop: '1rem' }}>{submitted}</pre>}
    </form>
  );
}
```

---

## Accessibility

- Uses `role="radiogroup"` for the container
- Each star has `role="radio"` with `aria-checked`
- Has `aria-valuenow`, `aria-valuemin`, and `aria-valuemax`
- Full keyboard navigation with arrow keys
- Home/End keys jump to 0/max values

---

## Related Components

- [Slider](./slider.md) - For selecting numeric values with a range
- [Input](./input.md) - For text input

---

## Additional Resources

- [Storybook: Rate Stories](https://bestax.io/storybook/?path=/story/form-rate)

:::tip Pro Tip
Use the `texts` prop to provide context for each rating level, helping users understand what each star value means.
:::

---

## Select


## Overview

The `Select` component provides a Bulma-styled dropdown for selecting one or more options. It supports color, size, rounded corners, loading, hover/focus state, multiselect, fullwidth, icons, and all Bulma helper props.

---

## Import

```tsx

```

---

## Props

| Prop           | Type                                           | Description                                      |
| -------------- | ---------------------------------------------- | ------------------------------------------------ |
| `color`        | `'primary' \| 'link' \| ... \| 'white'`        | Bulma color modifier.                            |
| `size`         | `'small' \| 'medium' \| 'large'`               | Size modifier.                                   |
| `isRounded`    | `boolean`                                      | Rounded select corners.                          |
| `isLoading`    | `boolean`                                      | Shows loading indicator.                         |
| `isHovered`    | `boolean`                                      | Forces hovered state on the inner select.        |
| `isFocused`    | `boolean`                                      | Forces focused state on the inner select.        |
| `isFullwidth`  | `boolean`                                      | Makes the select span the full width of parent.  |
| `isActive`     | `boolean`                                      | Applies Bulma's is-active modifier.              |
| `className`    | `string`                                       | Additional CSS classes.                          |
| `disabled`     | `boolean`                                      | Disables the select.                             |
| `multiple`     | `boolean`                                      | Allows multiple selections.                      |
| `multipleSize` | `number`                                       | Number of visible options in multiselect.        |
| `children`     | `React.ReactNode`                              | `<option>` elements.                             |
| ...            | All standard `<select>` and Bulma helper props | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

`Select` is a convenience component that internally composes `Field` and `Control`. For most form fields, use `<Select>` directly with its props (`label`, `color`, `size`, `iconLeftName`, `message`, `horizontal`, etc.). Reach for explicit `<Field>` + `<Control>` composition only when you need a layout the convenience props can't express — most commonly **form addons**, **horizontal layouts that mix multiple sub-fields**, or **fullwidth selects inside addons**.

### Default Select

A standard dropdown. The `children` prop provides the `<option>` elements.

```tsx live
<Select label="Default">
  <option value="">Please select</option>
  <option value="option1">Option 1</option>
  <option value="option2">Option 2</option>
</Select>
```

---

### Multi Select

Set the `multiple` prop to enable multi-selection. The `multipleSize` prop controls how many options are visible at once.

```tsx live
<Select label="Multi Select" multiple multipleSize={10}>
  <option value="huck">Huckleberry Finn</option>
  <option value="tom">Tom Sawyer</option>
  <option value="becky">Becky Thatcher</option>
  <option value="jim">Jim</option>
  <option value="pap">Pap Finn</option>
  <option value="duke">The Duke</option>
  <option value="king">The King</option>
  <option value="widow">Widow Douglas</option>
  <option value="judge">Judge Thatcher</option>
  <option value="sid">Sid Sawyer</option>
</Select>
```

---

### Colored Select

The `color` prop applies Bulma color modifiers.

```tsx live
<>
  <Select label="Primary" color="primary">
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
  </Select>
  <Select label="Link" color="link">
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
  </Select>
  <Select label="Info" color="info">
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
  </Select>
  <Select label="Success" color="success">
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
  </Select>
  <Select label="Warning" color="warning">
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
  </Select>
  <Select label="Danger" color="danger">
    <option value="1">Option 1</option>
    <option value="2">Option 2</option>
  </Select>
</>
```

---

### Rounded Style

The `isRounded` prop gives the select rounded corners.

```tsx live
<Select label="Rounded" isRounded>
  <option value="">Please select</option>
  <option value="option1">Option 1</option>
  <option value="option2">Option 2</option>
</Select>
```

---

### Sizes

The `size` prop controls the select's size.

```tsx live
<>
  <Select label="Small" size="small">
    <option value="">Please select</option>
    <option value="option1">Option 1</option>
    <option value="option2">Option 2</option>
  </Select>
  <Select label="Normal">
    <option value="">Please select</option>
    <option value="option1">Option 1</option>
    <option value="option2">Option 2</option>
  </Select>
  <Select label="Medium" size="medium">
    <option value="">Please select</option>
    <option value="option1">Option 1</option>
    <option value="option2">Option 2</option>
  </Select>
  <Select label="Large" size="large">
    <option value="">Please select</option>
    <option value="option1">Option 1</option>
    <option value="option2">Option 2</option>
  </Select>
</>
```

---

### States

`isHovered`, `isFocused`, and `isLoading` force the corresponding state on the select.

```tsx live
<>
  <Select label="Normal">
    <option value="">Please select</option>
    <option value="option1">Option 1</option>
  </Select>
  <Select label="Hover" isHovered>
    <option value="">Please select</option>
    <option value="option1">Option 1</option>
  </Select>
  <Select label="Focus" isFocused>
    <option value="">Please select</option>
    <option value="option1">Option 1</option>
  </Select>
  <Select label="Loading" isLoading>
    <option value="">Please select</option>
    <option value="option1">Option 1</option>
  </Select>
</>
```

---

### Loading States by Size

The loading indicator at every select size.

```tsx live
<>
  <Select label="Loading Small" size="small" isLoading>
    <option value="">Please select</option>
  </Select>
  <Select label="Loading Normal" isLoading>
    <option value="">Please select</option>
  </Select>
  <Select label="Loading Medium" size="medium" isLoading>
    <option value="">Please select</option>
  </Select>
  <Select label="Loading Large" size="large" isLoading>
    <option value="">Please select</option>
  </Select>
</>
```

---

### Disabled

Use the native `disabled` attribute to disable the select.

```tsx live
<Select label="Disabled" disabled>
  <option value="">Cannot change</option>
</Select>
```

---

### With Icons

Selects support a left icon only (Bulma's chevron occupies the right). Use the `iconLeftName` shortcut on `<Select>`.

```tsx live
<Select label="With Icons" iconLeftName="person">
  <option value="huck">Huckleberry Finn</option>
  <option value="tom">Tom Sawyer</option>
  <option value="becky">Becky Thatcher</option>
  <option value="jim">Jim</option>
  <option value="pap">Pap Finn</option>
</Select>
```

---

### With Icons and Size Variations

Match the icon size to the select size.

```tsx live
<>
  <Select
    label="With Icons Small"
    size="small"
    iconLeftName="person"
    iconLeftSize="small"
  >
    <option value="huck">Huckleberry Finn</option>
    <option value="tom">Tom Sawyer</option>
  </Select>
  <Select label="With Icons Normal" iconLeftName="person">
    <option value="huck">Huckleberry Finn</option>
    <option value="tom">Tom Sawyer</option>
  </Select>
  <Select
    label="With Icons Medium"
    size="medium"
    iconLeftName="person"
    iconLeftSize="medium"
  >
    <option value="huck">Huckleberry Finn</option>
    <option value="tom">Tom Sawyer</option>
  </Select>
  <Select
    label="With Icons Large"
    size="large"
    iconLeftName="person"
    iconLeftSize="large"
  >
    <option value="huck">Huckleberry Finn</option>
    <option value="tom">Tom Sawyer</option>
  </Select>
</>
```

---

### Form Addons

For multi-control rows like select + input + button, drop down to manual `Field` + `Control` composition.

#### Currency Select + Input + Button

A common pattern: a small select acting as a unit picker (currency, country code), an expanded input, and a submit button.

```tsx live
<Field hasAddons>
  <Control>
    <Select aria-label="Currency">
      <option>$</option>
      <option>£</option>
      <option>€</option>
    </Select>
  </Control>
  <Control isExpanded>
    <Input type="text" placeholder="Amount of money" />
  </Control>
  <Control>
    <Button>Transfer</Button>
  </Control>
</Field>
```

#### Fullwidth Select + Button

Use `isFullwidth` on the Select with `isExpanded` on its Control to make the dropdown grow to fill the row.

```tsx live
<Field hasAddons>
  <Control isExpanded>
    <Select isFullwidth aria-label="Country">
      <option>United States</option>
      <option>United Kingdom</option>
      <option>Canada</option>
      <option>France</option>
      <option>Germany</option>
    </Select>
  </Control>
  <Control>
    <Button color="primary">Choose</Button>
  </Control>
</Field>
```

---

### Horizontal — Select in Narrow Field

In horizontal forms, mark the inner `<Field narrow>` so it doesn't stretch the full row, and use `isFullwidth` on the Select to fill the narrow field.

```tsx live
<Field horizontal label="Department">
  <Field.Body>
    <Field narrow>
      <Control>
        <Select isFullwidth>
          <option>Business development</option>
          <option>Marketing</option>
          <option>Sales</option>
        </Select>
      </Control>
    </Field>
  </Field.Body>
</Field>
```

---

### Context-Aware Rendering

The `Select` component is context-aware: it detects whether it is already inside a `Field` or `Control` and adjusts its rendering accordingly. You can use it standalone with a `label` prop (it wraps itself in Field+Control), inside a `Field` (it skips its own Field), or inside both `Field` and `Control` (it renders only the raw select).

#### Default (with label)

```tsx live
<Select label="Country">
  <option value="">Please select</option>
  <option value="us">United States</option>
  <option value="uk">United Kingdom</option>
  <option value="ca">Canada</option>
</Select>
```

---

#### With Field Wrapper

```tsx live
function example() {
  return (
    <Field horizontal label="Country">
      <Field.Body>
        <Field>
          <Select>
            <option value="">Please select</option>
            <option value="us">United States</option>
            <option value="uk">United Kingdom</option>
            <option value="ca">Canada</option>
          </Select>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

```tsx live
function example() {
  return (
    <Field horizontal label="Country">
      <Field.Body>
        <Field>
          <Control iconLeftName="globe">
            <Select>
              <option value="">Please select</option>
              <option value="us">United States</option>
              <option value="uk">United Kingdom</option>
              <option value="ca">Canada</option>
            </Select>
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

## Accessibility

- Always provide a `<label>` (use Select's `label` prop, or wrap in `Field`) for accessible select usage.
- Use the `multiple` and `multipleSize` props for multi-select dropdowns.

---

## Related Components

- [`Control`](./control.md): For icons and loading.
- [`Field`](./field.md): For field grouping and labels.

---

## Additional Resources

- [Bulma Select Documentation](https://bulma.io/documentation/form/select/)
- [Storybook: Select Stories](https://bestax.io/storybook/?path=/story/form-select--default)

---

## Slider


## Overview

The `Slider` component provides a range slider input for selecting values within a range. It supports different sizes, colors, and optional value display.

---

## Import

```tsx

```

---

## Props

| Prop               | Type                                                                            | Default        | Description                                                                                 |
| ------------------ | ------------------------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------------- |
| `value`            | `number`                                                                        | —              | Controlled value.                                                                           |
| `defaultValue`     | `number`                                                                        | `0`            | Default value for uncontrolled usage.                                                       |
| `min`              | `number`                                                                        | `0`            | Minimum value.                                                                              |
| `max`              | `number`                                                                        | `100`          | Maximum value.                                                                              |
| `step`             | `number`                                                                        | `1`            | Step increment.                                                                             |
| `size`             | `'small'` \| `'medium'` \| `'large'`                                            | —              | Size variant.                                                                               |
| `color`            | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` | —              | Color variant.                                                                              |
| `isRounded`        | `boolean`                                                                       | `false`        | Use rounded track ends.                                                                     |
| `isCircle`         | `boolean`                                                                       | `false`        | Use circular thumb.                                                                         |
| `disabled`         | `boolean`                                                                       | `false`        | Whether the slider is disabled.                                                             |
| `showOutput`       | `boolean`                                                                       | `false`        | Show current value tooltip.                                                                 |
| `onChange`         | `(value: number) => void`                                                       | —              | Callback when value changes.                                                                |
| `formatOutput`     | `(value: number) => string`                                                     | —              | Format function for output display.                                                         |
| `tooltip`          | `'auto'` \| `'always'` \| `'hidden'`                                            | —              | Controls tooltip visibility on the thumb.                                                   |
| `ticks`            | `boolean`                                                                       | —              | Shows tick marks along the track.                                                           |
| `marks`            | `SliderMark[]`                                                                  | —              | Custom labeled marks along the track. Each mark has `{ value: number; label?: ReactNode }`. |
| `orientation`      | `'horizontal'` \| `'vertical'`                                                  | `'horizontal'` | Orientation of the slider.                                                                  |
| `scale`            | `(value: number) => number`                                                     | —              | Function to scale the displayed value.                                                      |
| `getAriaValueText` | `(value: number) => string`                                                     | —              | Function to generate the `aria-valuetext` attribute.                                        |
| `range`            | `boolean`                                                                       | `false`        | Enables range mode with two thumbs.                                                         |
| `minDistance`      | `number`                                                                        | `0`            | Minimum distance between thumbs in range mode.                                              |
| `ariaLabel`        | `string` \| `[string, string]`                                                  | —              | ARIA label(s) for the slider thumb(s).                                                      |
| `className`        | `string`                                                                        | —              | Additional CSS classes.                                                                     |
| `ref`              | `React.Ref<HTMLElement>`                                                        | —              | Ref forwarded to the input element.                                                         |
| ...                | All standard HTML and Bulma helper props                                        |                | (See [Helper Props](../helpers/usebulmaclasses))                                            |

---

## Usage

### Basic Slider

A simple range slider.

```tsx live
function example() {
  const [value, setValue] = useState(50);
  return (
    <Block>
      <Slider value={value} onChange={setValue} />
      <Paragraph mt="2">Value: {value}</Paragraph>
    </Block>
  );
}
```

---

### With Output Display

Slider showing the current value tooltip.

```tsx live
function example() {
  const [value, setValue] = useState(50);
  return (
    <Block>
      <Slider value={value} onChange={setValue} showOutput color="primary" />
      <Paragraph mt="4">Value: {value}</Paragraph>
    </Block>
  );
}
```

---

### Color Variants

Sliders with different color options.

```tsx live
<Block display="flex" flexDirection="column" gap="5">
  <Slider defaultValue={50} color="primary" showOutput />
  <Slider defaultValue={50} color="success" showOutput />
  <Slider defaultValue={50} color="info" showOutput />
  <Slider defaultValue={50} color="warning" showOutput />
  <Slider defaultValue={50} color="danger" showOutput />
</Block>
```

---

### Size Variants

Sliders in different sizes.

```tsx live
<Block display="flex" flexDirection="column" gap="5">
  <Block>
    <Paragraph mb="1">Small</Paragraph>
    <Slider defaultValue={50} size="small" color="primary" />
  </Block>
  <Block>
    <Paragraph mb="1">Normal</Paragraph>
    <Slider defaultValue={50} color="primary" />
  </Block>
  <Block>
    <Paragraph mb="1">Medium</Paragraph>
    <Slider defaultValue={50} size="medium" color="primary" />
  </Block>
  <Block>
    <Paragraph mb="1">Large</Paragraph>
    <Slider defaultValue={50} size="large" color="primary" />
  </Block>
</Block>
```

---

### Rounded and Circle

Slider with rounded track and circular thumb.

```tsx live
<Block display="flex" flexDirection="column" gap="5">
  <Block>
    <Paragraph mb="1">Rounded</Paragraph>
    <Slider defaultValue={50} isRounded color="info" showOutput />
  </Block>
  <Block>
    <Paragraph mb="1">Circle Thumb</Paragraph>
    <Slider defaultValue={50} isCircle color="success" showOutput />
  </Block>
  <Block>
    <Paragraph mb="1">Both</Paragraph>
    <Slider defaultValue={50} isRounded isCircle color="warning" showOutput />
  </Block>
</Block>
```

---

### Custom Range

Slider with custom min, max, and step values.

```tsx live
function example() {
  const [value, setValue] = useState(500);
  return (
    <Block>
      <Slider
        value={value}
        onChange={setValue}
        min={0}
        max={1000}
        step={50}
        showOutput
        color="primary"
      />
      <Paragraph mt="4">Value: ${value}</Paragraph>
    </Block>
  );
}
```

---

### Custom Output Format

Slider with formatted output display.

```tsx live
function example() {
  const [value, setValue] = useState(50);
  return (
    <Block>
      <Slider
        value={value}
        onChange={setValue}
        showOutput
        color="success"
        formatOutput={v => `${v}%`}
      />
      <Paragraph mt="4">Progress: {value}%</Paragraph>
    </Block>
  );
}
```

---

### Disabled Slider

A disabled slider that cannot be interacted with.

```tsx live
<Slider defaultValue={30} disabled color="primary" />
```

---

### Context-Aware Rendering

The `Slider` component is context-aware: it detects whether it is already inside a `Field` and adjusts its rendering accordingly. This means you can use it standalone with a `label` prop (it wraps itself in a Field), or inside a `Field` (it skips rendering its own).

#### Default (with label)

The simplest usage — the component automatically renders its own Field wrapper.

```tsx live
<Slider label="Volume" defaultValue={50} color="primary" />
```

---

#### With Field Wrapper

When you need manual control over the Field layout (e.g., horizontal forms), wrap the component in `Field`. The component detects it's inside a Field and skips rendering its own.

```tsx live
function example() {
  return (
    <Field horizontal label="Volume">
      <Field.Body>
        <Field>
          <Slider defaultValue={50} color="primary" />
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

For full manual composition, wrap in both Field and Control. The component detects the Field context and renders only the slider element.

```tsx live
function example() {
  return (
    <Field horizontal label="Volume">
      <Field.Body>
        <Field>
          <Control iconLeftName="volume-up">
            <Slider defaultValue={50} color="primary" />
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

## Controlled vs Uncontrolled

### Controlled Mode

Use `value` and `onChange` to manage state externally:

```tsx
const [value, setValue] = useState(50);
<Slider value={value} onChange={setValue} />;
```

### Uncontrolled Mode

Use `defaultValue` for internal state management:

```tsx
<Slider defaultValue={50} />
```

---

## Form Submission

`Slider` uses a native `<input type="range">` and is HTML-form-compatible. In single-value mode pass a `name` prop. In range mode use `nameLow` and `nameHigh` so each thumb submits as its own field.

| Mode   | Prop(s)                                                                                                  |
| ------ | -------------------------------------------------------------------------------------------------------- |
| Single | `name` (forwarded to the single `<input type="range">`)                                                  |
| Range  | `nameLow` (low thumb), `nameHigh` (high thumb) — both render as separate `<input type="range">` elements |

```tsx live
function SliderRangeFormDemo() {
  const [submitted, setSubmitted] = React.useState('');
  return (
    <form
      onSubmit={e => {
        e.preventDefault();
        const fd = new FormData(e.currentTarget);
        setSubmitted(JSON.stringify(Array.from(fd.entries()), null, 2));
      }}
    >
      <Slider
        range
        nameLow="priceMin"
        nameHigh="priceMax"
        defaultValue={[20, 80]}
        showOutput
      />
      
        <button type="submit" className="button is-primary">
          Submit
        </button>
      
      {submitted && <pre style={{ marginTop: '1rem' }}>{submitted}</pre>}
    </form>
  );
}
```

---

## Accessibility

- Uses native `<input type="range">` element
- Has `aria-valuenow`, `aria-valuemin`, and `aria-valuemax` attributes
- Fully keyboard accessible with arrow keys
- Focus states clearly visible

---

## Related Components

- [Numberinput](./numberinput.md) - For numeric input with +/- buttons
- [Progress](../elements/progress.md) - For displaying progress

---

## Additional Resources

- [Storybook: Slider Stories](https://bestax.io/storybook/?path=/story/form-slider)

:::tip Pro Tip
Use the `formatOutput` prop to display values with units like percentages, currencies, or custom formats.
:::

---

## Switch


## Overview

The `Switch` component provides a toggle switch for boolean on/off states. It's built on top of a checkbox input and supports multiple colors, sizes, and style variants. Perfect for settings pages, feature toggles, and preference selections.

---

## Import

```tsx

```

---

## Props

| Prop             | Type                                                                                                                                                                                                                                                                                     | Default | Description                                        |
| ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------- |
| `color`          | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`                                                                                                                                                                                                          | —       | Color variant for the switch.                      |
| `size`           | `'small'` \| `'normal'` \| `'medium'` \| `'large'`                                                                                                                                                                                                                                       | —       | Size of the switch.                                |
| `isRounded`      | `boolean`                                                                                                                                                                                                                                                                                | `false` | Use rounded switch style.                          |
| `isThin`         | `boolean`                                                                                                                                                                                                                                                                                | `false` | Use thin switch style.                             |
| `isOutlined`     | `boolean`                                                                                                                                                                                                                                                                                | `false` | Use outlined switch style.                         |
| `isRtl`          | `boolean`                                                                                                                                                                                                                                                                                | `false` | Right-to-left layout (label on left).              |
| `disabled`       | `boolean`                                                                                                                                                                                                                                                                                | `false` | Whether the switch is disabled.                    |
| `checked`        | `boolean`                                                                                                                                                                                                                                                                                | —       | Controlled checked state.                          |
| `defaultChecked` | `boolean`                                                                                                                                                                                                                                                                                | `false` | Default checked state for uncontrolled usage.      |
| `onChange`       | `(e: ChangeEvent<HTMLInputElement>) => void`                                                                                                                                                                                                                                             | —       | Callback when switch state changes.                |
| `passiveType`    | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`                                                                                                                                                                                                          | —       | Color when the switch is in the off/passive state. |
| `textColor`      | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                                 |
| `children`       | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Label content for the switch.                      |
| `className`      | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                            |
| `ref`            | `React.Ref<HTMLInputElement>`                                                                                                                                                                                                                                                            | —       | Ref forwarded to the input element.                |
| ...              | All standard HTML input props and Bulma helper props                                                                                                                                                                                                                                     |         | (See [Helper Props](../helpers/usebulmaclasses))   |

---

## Usage

### Basic Switch

A simple switch with a label.

```tsx live
function example() {
  return <Switch>Enable notifications</Switch>;
}
```

---

### Colors

Switch with different color variants.

```tsx live
function example() {
  return (
    <Block display="flex" flexDirection="column" gap="4">
      <Switch color="primary" defaultChecked>
        Primary
      </Switch>
      <Switch color="link" defaultChecked>
        Link
      </Switch>
      <Switch color="info" defaultChecked>
        Info
      </Switch>
      <Switch color="success" defaultChecked>
        Success
      </Switch>
      <Switch color="warning" defaultChecked>
        Warning
      </Switch>
      <Switch color="danger" defaultChecked>
        Danger
      </Switch>
    </Block>
  );
}
```

---

### Sizes

Switch with different size variants.

```tsx live
function example() {
  return (
    <Block display="flex" flexDirection="column" gap="4">
      <Switch size="small" defaultChecked>
        Small
      </Switch>
      <Switch size="normal" defaultChecked>
        Normal
      </Switch>
      <Switch size="medium" defaultChecked>
        Medium
      </Switch>
      <Switch size="large" defaultChecked>
        Large
      </Switch>
    </Block>
  );
}
```

---

### Rounded Style

Switch with rounded (pill) style.

```tsx live
function example() {
  return (
    <Switch isRounded color="success" defaultChecked>
      Rounded switch
    </Switch>
  );
}
```

---

### Thin Style

Switch with thin track style.

```tsx live
function example() {
  return (
    <Switch isThin color="info" defaultChecked>
      Thin switch
    </Switch>
  );
}
```

---

### Outlined Style

Switch with outlined style.

```tsx live
function example() {
  return (
    <Block display="flex" flexDirection="column" gap="4">
      <Switch isOutlined color="primary" defaultChecked>
        Primary outlined
      </Switch>
      <Switch isOutlined color="success" defaultChecked>
        Success outlined
      </Switch>
    </Block>
  );
}
```

---

### RTL Layout

Switch with label on the left side.

```tsx live
function example() {
  return (
    <Switch isRtl color="primary" defaultChecked>
      Label on left
    </Switch>
  );
}
```

---

### Disabled State

Disabled switches.

```tsx live
function example() {
  return (
    <Block display="flex" flexDirection="column" gap="4">
      <Switch disabled>Disabled unchecked</Switch>
      <Switch disabled defaultChecked color="success">
        Disabled checked
      </Switch>
    </Block>
  );
}
```

---

### Controlled Usage

Switch with controlled state.

```tsx live
function example() {
  const [isEnabled, setIsEnabled] = useState(false);

  return (
    <Block>
      <Switch
        color="primary"
        checked={isEnabled}
        onChange={e => setIsEnabled(e.target.checked)}
      >
        Feature is {isEnabled ? 'enabled' : 'disabled'}
      </Switch>
      <Paragraph mt="2">
        State: {isEnabled ? 'ON' : 'OFF'}
      </Paragraph>
    </Block>
  );
}
```

---

### Settings Panel Example

Multiple switches for a settings panel.

```tsx live
function example() {
  const [settings, setSettings] = useState({
    notifications: true,
    darkMode: false,
    autoSave: true,
  });

  const updateSetting = key => e => {
    setSettings(prev => ({ ...prev, [key]: e.target.checked }));
  };

  return (
    <Block style={{ maxWidth: '300px' }}>
      <Title size="5">Settings</Title>
      <Block display="flex" flexDirection="column" gap="4">
        <Switch
          color="primary"
          checked={settings.notifications}
          onChange={updateSetting('notifications')}
        >
          Push notifications
        </Switch>
        <Switch
          color="info"
          checked={settings.darkMode}
          onChange={updateSetting('darkMode')}
        >
          Dark mode
        </Switch>
        <Switch
          color="success"
          checked={settings.autoSave}
          onChange={updateSetting('autoSave')}
        >
          Auto-save
        </Switch>
      </Block>
    </Block>
  );
}
```

---

## Accessibility

- The Switch is built on a native checkbox input for proper keyboard navigation
- Use the `children` prop to provide a visible label
- For icon-only switches, provide an `aria-label` prop
- The switch can be focused and toggled with keyboard (Space/Enter)

---

## Related

- [Checkbox](./checkbox.md) - Standard checkbox input
- [Field](./field.md) - Form field wrapper

---

## Taginput


## Overview

The `Taginput` component provides a tag/chip input field for managing multiple tags. It supports autocomplete suggestions, custom tag styling, and various input behaviors.

---

## Import

```tsx

```

---

## Props

| Prop                | Type                                                                                                     | Default          | Description                                           |
| ------------------- | -------------------------------------------------------------------------------------------------------- | ---------------- | ----------------------------------------------------- |
| `value`             | `TaginputTag[]`                                                                                          | —                | The current tags (controlled).                        |
| `defaultValue`      | `TaginputTag[]`                                                                                          | `[]`             | Default tags (uncontrolled).                          |
| `data`              | `string[]`                                                                                               | `[]`             | Autocomplete suggestions.                             |
| `placeholder`       | `string`                                                                                                 | —                | Placeholder text when no tags.                        |
| `field`             | `string`                                                                                                 | `'label'`        | Object property to use as display field.              |
| `allowNew`          | `boolean`                                                                                                | `true`           | Allow creating new tags not in suggestions.           |
| `allowDuplicates`   | `boolean`                                                                                                | `false`          | Allow duplicate tags.                                 |
| `openOnFocus`       | `boolean`                                                                                                | `false`          | Open autocomplete dropdown on focus.                  |
| `removeOnKeys`      | `boolean`                                                                                                | `true`           | Remove tag on backspace.                              |
| `confirmKeys`       | `string[]`                                                                                               | `['Enter', ',']` | Keys to confirm tag creation.                         |
| `closable`          | `boolean`                                                                                                | `true`           | Show close button on tags.                            |
| `attached`          | `boolean`                                                                                                | `false`          | Attach tags visually.                                 |
| `maxTags`           | `number`                                                                                                 | —                | Maximum number of tags allowed.                       |
| `maxlength`         | `number`                                                                                                 | —                | Maximum length of input.                              |
| `disabled`          | `boolean`                                                                                                | `false`          | Whether the input is disabled.                        |
| `readonly`          | `boolean`                                                                                                | `false`          | Whether the input is read-only.                       |
| `color`             | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`                          | —                | Input color variant.                                  |
| `tagColor`          | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'dark'` \| `'light'` | —                | Tag color variant.                                    |
| `size`              | `'small'` \| `'medium'` \| `'large'`                                                                     | —                | Size variant.                                         |
| `onChange`          | `(tags: TaginputTag[]) => void`                                                                          | —                | Callback when tags change.                            |
| `onAdd`             | `(tag: TaginputTag) => void`                                                                             | —                | Callback when tag is added.                           |
| `onRemove`          | `(tag: TaginputTag, index: number) => void`                                                              | —                | Callback when tag is removed.                         |
| `onTyping`          | `(value: string) => void`                                                                                | —                | Callback when typing in input.                        |
| `tagTemplate`       | `(tag: TaginputTag) => React.ReactNode`                                                                  | —                | Custom render for tags.                               |
| `rounded`           | `boolean`                                                                                                | `false`          | Applies rounded corners to the tags.                  |
| `ellipsis`          | `boolean`                                                                                                | `false`          | Truncates long tag text with ellipsis.                |
| `hasCounter`        | `boolean`                                                                                                | `true`           | Shows a counter of the number of tags.                |
| `onPasteSeparators` | `string[]`                                                                                               | `[',']`          | Characters that split pasted text into tags.          |
| `beforeAdding`      | `(tag: string) => boolean`                                                                               | —                | Validation function called before adding a tag.       |
| `createTag`         | `(input: string) => TaginputTag`                                                                         | —                | Custom function for creating tag objects from input.  |
| `keepFirst`         | `boolean`                                                                                                | `false`          | Keeps the first autocomplete suggestion highlighted.  |
| `keepOpen`          | `boolean`                                                                                                | `true`           | Keeps the autocomplete dropdown open after selection. |
| `loading`           | `boolean`                                                                                                | `false`          | Shows a loading indicator.                            |
| `ariaCloseLabel`    | `string`                                                                                                 | —                | ARIA label for tag close buttons.                     |
| `icon`              | `string`                                                                                                 | —                | Icon name for the input.                              |
| `iconLibrary`       | `'fa'` \| `'mdi'` \| `'ion'` \| `'material-icons'` \| `'material-symbols'`                               | —                | Icon library to use.                                  |
| `iconVariant`       | `string`                                                                                                 | —                | Icon style variant.                                   |
| `iconFeatures`      | `string` \| `string[]`                                                                                   | —                | Additional icon modifiers.                            |
| `className`         | `string`                                                                                                 | —                | Additional CSS classes.                               |
| `ref`               | `React.Ref<HTMLElement>`                                                                                 | —                | Ref forwarded to the input element.                   |
| ...                 | All standard HTML and Bulma helper props                                                                 |                  | (See [Helper Props](../helpers/usebulmaclasses))      |

### TaginputTag

Can be either a `string` or an object with:

| Prop    | Type     | Description               |
| ------- | -------- | ------------------------- |
| `value` | `string` | The tag value.            |
| `label` | `string` | Display label (optional). |

---

## Usage

### Basic Taginput

Simple tag input without suggestions.

```tsx live
function example() {
  const [tags, setTags] = useState(['React', 'TypeScript']);

  return (
    <Block>
      <Taginput value={tags} onChange={setTags} placeholder="Add a tag..." />
      <Paragraph mt="2" textColor="grey">
        Tags: {tags.join(', ')}
      </Paragraph>
    </Block>
  );
}
```

---

### With Autocomplete

Tag input with suggestion dropdown.

```tsx live
function example() {
  const [tags, setTags] = useState(['React']);
  const suggestions = [
    'React',
    'Vue',
    'Angular',
    'Svelte',
    'TypeScript',
    'JavaScript',
    'Python',
    'Go',
  ];

  return (
    <Taginput
      value={tags}
      onChange={setTags}
      data={suggestions}
      placeholder="Add frameworks..."
      openOnFocus
    />
  );
}
```

---

### Restrict to Suggestions

Only allow tags from the suggestion list.

```tsx live
function example() {
  const [tags, setTags] = useState([]);
  const categories = [
    'Bug',
    'Feature',
    'Documentation',
    'Enhancement',
    'Question',
  ];

  return (
    <Block>
      <Taginput
        value={tags}
        onChange={setTags}
        data={categories}
        allowNew={false}
        placeholder="Select categories..."
        openOnFocus
      />
      <Paragraph mt="2" textColor="grey" textSize="7">
        Only predefined categories can be selected
      </Paragraph>
    </Block>
  );
}
```

---

### Tag Colors

Tags with different color variants.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <Taginput
    defaultValue={['Primary']}
    tagColor="primary"
    placeholder="Primary tags..."
  />
  <Taginput
    defaultValue={['Success']}
    tagColor="success"
    placeholder="Success tags..."
  />
  <Taginput
    defaultValue={['Info']}
    tagColor="info"
    placeholder="Info tags..."
  />
  <Taginput
    defaultValue={['Warning']}
    tagColor="warning"
    placeholder="Warning tags..."
  />
  <Taginput
    defaultValue={['Danger']}
    tagColor="danger"
    placeholder="Danger tags..."
  />
  <Taginput
    defaultValue={['Dark']}
    tagColor="dark"
    placeholder="Dark tags..."
  />
</Block>
```

---

### Size Variants

Tag inputs in different sizes.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <Taginput
    defaultValue={['Small']}
    size="small"
    tagColor="primary"
    placeholder="Small..."
  />
  <Taginput
    defaultValue={['Normal']}
    tagColor="primary"
    placeholder="Normal..."
  />
  <Taginput
    defaultValue={['Medium']}
    size="medium"
    tagColor="primary"
    placeholder="Medium..."
  />
  <Taginput
    defaultValue={['Large']}
    size="large"
    tagColor="primary"
    placeholder="Large..."
  />
</Block>
```

---

### Maximum Tags

Limit the number of tags allowed.

```tsx live
function example() {
  const [tags, setTags] = useState(['One', 'Two']);

  return (
    <Block>
      <Taginput
        value={tags}
        onChange={setTags}
        maxTags={3}
        tagColor="info"
        placeholder="Max 3 tags..."
      />
      <Paragraph mt="2" textColor="grey" textSize="7">
        {3 - tags.length} tags remaining
      </Paragraph>
    </Block>
  );
}
```

---

### Allow Duplicates

Enable duplicate tag values.

```tsx live
function example() {
  const [tags, setTags] = useState(['Tag']);

  return (
    <Taginput
      value={tags}
      onChange={setTags}
      allowDuplicates
      tagColor="warning"
      placeholder="Duplicates allowed..."
    />
  );
}
```

---

### Custom Confirm Keys

Change which keys create a new tag.

```tsx live
function example() {
  const [tags, setTags] = useState([]);

  return (
    <Block>
      <Taginput
        value={tags}
        onChange={setTags}
        confirmKeys={['Enter', 'Tab', ' ']}
        tagColor="success"
        placeholder="Press Enter, Tab, or Space..."
      />
      <Paragraph mt="2" textColor="grey" textSize="7">
        Space also creates a new tag
      </Paragraph>
    </Block>
  );
}
```

---

### Read-only and Disabled

Display modes for tags.

```tsx live
<Block display="flex" flexDirection="column" gap="4">
  <Block>
    <Paragraph mb="1">Read-only:</Paragraph>
    <Taginput defaultValue={['React', 'TypeScript']} readonly tagColor="info" />
  </Block>
  <Block>
    <Paragraph mb="1">Disabled:</Paragraph>
    <Taginput defaultValue={['React', 'TypeScript']} disabled tagColor="info" />
  </Block>
</Block>
```

---

### Non-closable Tags

Tags without the delete button.

```tsx live
<Taginput
  defaultValue={['Fixed', 'Tags']}
  closable={false}
  tagColor="primary"
  placeholder="Cannot remove tags..."
/>
```

---

### Context-Aware Rendering

The `Taginput` component is context-aware: it detects whether it is already inside a `Field` and adjusts its rendering accordingly. This means you can use it standalone with a `label` prop (it wraps itself in a Field), or inside a `Field` (it skips rendering its own).

:::note
Taginput does not use ControlContext, so the "With Field and Control Wrappers" example below uses Field wrapping only. The Control wrapper is shown for layout consistency but does not change the component's internal rendering.
:::

#### Default (with label)

The simplest usage — the component automatically renders its own Field wrapper.

```tsx live
<Taginput
  label="Tags"
  defaultValue={['React', 'TypeScript']}
  placeholder="Add a tag..."
  tagColor="primary"
/>
```

---

#### With Field Wrapper

When you need manual control over the Field layout (e.g., horizontal forms), wrap the component in `Field`. The component detects it's inside a Field and skips rendering its own.

```tsx live
function example() {
  return (
    <Field horizontal label="Tags">
      <Field.Body>
        <Field>
          <Taginput
            defaultValue={['React', 'TypeScript']}
            placeholder="Add a tag..."
            tagColor="primary"
          />
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

For full manual composition, wrap in both Field and Control. Taginput does not consume ControlContext, but the Field wrapper is still detected and its own Field is skipped.

For an icon, use Taginput's own `icon` prop rather than `<Control iconLeftName>` — Bulma's `has-icons-left` only adjusts padding on `.input`/`.select`, not on `.taginput`, so wrapping with Control's icon causes the icon to overlap the tags.

```tsx live
function example() {
  return (
    <Field horizontal label="Tags">
      <Field.Body>
        <Field>
          <Control>
            <Taginput
              icon="tags"
              defaultValue={['React', 'TypeScript']}
              placeholder="Add a tag..."
              tagColor="primary"
            />
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

## Keyboard Navigation

| Key         | Action                             |
| ----------- | ---------------------------------- |
| `Enter`     | Create tag from input              |
| `,`         | Create tag from input (default)    |
| `Backspace` | Remove last tag (when input empty) |
| `↓`         | Open/navigate suggestions          |
| `↑`         | Navigate suggestions up            |
| `Escape`    | Close suggestions dropdown         |

---

## Controlled vs Uncontrolled

### Controlled Mode

Use `value` and `onChange` to manage state externally:

```tsx
const [tags, setTags] = useState(['React']);
<Taginput value={tags} onChange={setTags} />;
```

### Uncontrolled Mode

Use `defaultValue` for internal state management:

```tsx
<Taginput defaultValue={['React', 'TypeScript']} />
```

---

## Form Submission

`Taginput` is an HTML form element. Pass a `name` prop and one hidden `<input>` per tag is rendered, producing standard form-encoded array submission (e.g., `tags=react&tags=vue&tags=angular`). Standard server-side parsers (PHP, Express body-parser, etc.) handle this format natively.

| Prop   | Description                                                      |
| ------ | ---------------------------------------------------------------- |
| `name` | Form field name. When set, one hidden input per tag is rendered. |
| `form` | Optional id of the form the hidden inputs belong to.             |

```tsx live
function TaginputFormDemo() {
  const [submitted, setSubmitted] = React.useState('');
  return (
    <form
      onSubmit={e => {
        e.preventDefault();
        const fd = new FormData(e.currentTarget);
        setSubmitted(JSON.stringify(Array.from(fd.entries()), null, 2));
      }}
    >
      <Taginput
        name="tags"
        defaultValue={['react', 'vue', 'angular']}
        placeholder="Add a tag…"
      />
      
        <button type="submit" className="button is-primary">
          Submit
        </button>
      
      {submitted && <pre style={{ marginTop: '1rem' }}>{submitted}</pre>}
    </form>
  );
}
```

---

## Accessibility

- Input has `aria-label="Add tag"` for screen readers
- Tags are keyboard navigable
- Delete buttons have proper `aria-label`
- Autocomplete dropdown follows ARIA listbox pattern

---

## Related Components

- [Autocomplete](./autocomplete.md) - For single value autocomplete
- [Input](./input.md) - For basic text input
- [Tag](../elements/tag.md) - For displaying tags

---

## Additional Resources

- [Storybook: Taginput Stories](https://bestax.io/storybook/?path=/story/form-taginput)

:::tip Pro Tip
Set `allowNew={false}` when you need strict control over allowed values, such as selecting from predefined categories or labels.
:::

---

## TextArea


## Overview

The `TextArea` component provides a Bulma-styled multi-line text input, supporting color, size, rounded corners, static/read-only state, hover/focus/loading states, fixed size, and all Bulma helper props.

---

## Import

```tsx

```

---

## Props

| Prop           | Type                                             | Description                                      |
| -------------- | ------------------------------------------------ | ------------------------------------------------ |
| `color`        | `'primary' \| 'link' \| ... \| 'white'`          | Bulma color modifier.                            |
| `size`         | `'small' \| 'medium' \| 'large'`                 | Size modifier.                                   |
| `isRounded`    | `boolean`                                        | Rounded textarea corners.                        |
| `isStatic`     | `boolean`                                        | Renders textarea as static (styled readonly).    |
| `isHovered`    | `boolean`                                        | Applies hovered state.                           |
| `isFocused`    | `boolean`                                        | Applies focused state.                           |
| `isLoading`    | `boolean`                                        | Shows loading indicator on the wrapping Control. |
| `isActive`     | `boolean`                                        | Applies Bulma's is-active modifier.              |
| `hasFixedSize` | `boolean`                                        | Fixed textarea size (no resize).                 |
| `className`    | `string`                                         | Additional CSS classes.                          |
| `disabled`     | `boolean`                                        | Disables the textarea.                           |
| `readOnly`     | `boolean`                                        | Read-only textarea.                              |
| `rows`         | `number`                                         | Number of visible text lines.                    |
| ...            | All standard `<textarea>` and Bulma helper props | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

`TextArea` is a convenience component that internally composes `Field` and `Control`. For most multi-line inputs, use `<TextArea>` directly with its props (`label`, `color`, `size`, `rows`, `hasFixedSize`, `isLoading`, `message`, `horizontal`, etc.). Bulma doesn't document textareas in addons or grouped layouts, so the convenience form covers nearly every case. Reach for explicit `<Field>` + `<Control>` only for very custom layouts.

### Default

A standard multi-line text input. The `placeholder` prop provides hint text.

```tsx live
<TextArea label="Default" placeholder="e.g. Hello world" />
```

---

### Row Count

Set the `rows` prop to control the visible number of text lines.

```tsx live
<TextArea label="Rows" rows={10} placeholder="10 rows" />
```

---

### Colors

The `color` prop applies Bulma color modifiers to visually distinguish input fields based on context or validation state.

```tsx live
<>
  <TextArea label="Primary" color="primary" placeholder="Primary textarea" />
  <TextArea label="Link" color="link" placeholder="Link textarea" />
  <TextArea label="Info" color="info" placeholder="Info textarea" />
  <TextArea label="Success" color="success" placeholder="Success textarea" />
  <TextArea label="Warning" color="warning" placeholder="Warning textarea" />
  <TextArea label="Danger" color="danger" placeholder="Danger textarea" />
</>
```

---

### Sizes

The `size` prop controls the overall size of the textarea.

```tsx live
<>
  <TextArea label="Small" size="small" placeholder="Small textarea" />
  <TextArea label="Normal" placeholder="Normal textarea" />
  <TextArea label="Medium" size="medium" placeholder="Medium textarea" />
  <TextArea label="Large" size="large" placeholder="Large textarea" />
</>
```

---

### States

`isHovered`, `isFocused`, and `isLoading` force the corresponding state on the textarea.

```tsx live
<>
  <TextArea label="Normal" placeholder="Normal textarea" />
  <TextArea label="Hover" isHovered placeholder="Hovered textarea" />
  <TextArea label="Focus" isFocused placeholder="Focused textarea" />
  <TextArea label="Loading" isLoading placeholder="Loading textarea" />
</>
```

---

### Loading States by Size

The loading indicator at every textarea size. Use `controlSize` on `<TextArea>` to scale the spinner to match.

```tsx live
<>
  <TextArea
    label="Loading Small"
    size="small"
    controlSize="small"
    isLoading
    placeholder="Small loading textarea"
  />
  <TextArea
    label="Loading Normal"
    isLoading
    placeholder="Normal loading textarea"
  />
  <TextArea
    label="Loading Medium"
    size="medium"
    controlSize="medium"
    isLoading
    placeholder="Medium loading textarea"
  />
  <TextArea
    label="Loading Large"
    size="large"
    controlSize="large"
    isLoading
    placeholder="Large loading textarea"
  />
</>
```

---

### Disabled & Read Only

Disabled textareas cannot be interacted with; read-only textareas can be focused but not edited.

```tsx live
<>
  <TextArea label="Disabled" disabled placeholder="Disabled textarea" />
  <TextArea label="Read Only" readOnly value="This content is readonly" />
</>
```

---

### Fixed Size

Set `hasFixedSize` to prevent the textarea from being user-resized.

```tsx live
<TextArea
  label="Fixed Size"
  hasFixedSize
  rows={3}
  placeholder="Fixed size textarea"
/>
```

---

### Horizontal

Use `horizontal` to render the label to the left of the textarea.

```tsx live
<TextArea
  horizontal
  label="Question"
  placeholder="Explain how we can help you"
  rows={4}
/>
```

---

### Context-Aware Rendering

The `TextArea` component is context-aware: it detects whether it is already inside a `Field` or `Control` and adjusts its rendering accordingly. You can use it standalone with a `label` prop (it wraps itself in Field+Control), inside a `Field` (it skips its own Field), or inside both `Field` and `Control` (it renders only the raw textarea).

#### Default (with label)

```tsx live
<TextArea label="Message" placeholder="Enter your message" />
```

---

#### With Field Wrapper

```tsx live
function example() {
  return (
    <Field horizontal label="Message">
      <Field.Body>
        <Field>
          <TextArea placeholder="Enter your message" />
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

#### With Field and Control Wrappers

```tsx live
function example() {
  return (
    <Field horizontal label="Message">
      <Field.Body>
        <Field>
          <Control iconLeftName="comment">
            <TextArea placeholder="Enter your message" />
          </Control>
        </Field>
      </Field.Body>
    </Field>
  );
}
```

---

## Accessibility

- Always provide a `<label>` (use TextArea's `label` prop, or wrap in `Field`) for accessible usage.
- Use the `rows` prop to set an appropriate height for your content.

---

## Related Components

- [`Control`](./control.md): For loading.
- [`Field`](./field.md): For field grouping and labels.

---

## Additional Resources

- [Bulma Textarea Documentation](https://bulma.io/documentation/form/textarea/)
- [Storybook: TextArea Stories](https://bestax.io/storybook/?path=/story/form-textarea--default)

---

## Cell


## Overview

The `Cell` component provides a single Bulma grid cell for use inside the [`Grid`](./grid.md) component. It supports all Bulma grid CSS classes for manual placement and spanning, color/background helpers, and all utility/HTML props. Use `Cell` to control column/row start, end, and span within modern CSS grid layouts.

---

## Import

```tsx

```

---

## Props

| Prop         | Type                                                                                                                                                                                                                                                                                     | Description                                                                        |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `colStart`   | `number`                                                                                                                                                                                                                                                                                 | Which column the cell starts at (Bulma: `is-col-start-x`).                         |
| `colFromEnd` | `number`                                                                                                                                                                                                                                                                                 | Which column the cell ends at, counting from the end (Bulma: `is-col-from-end-x`). |
| `colSpan`    | `number`                                                                                                                                                                                                                                                                                 | How many columns the cell will span (Bulma: `is-col-span-x`).                      |
| `rowStart`   | `number`                                                                                                                                                                                                                                                                                 | Which row the cell starts at (Bulma: `is-row-start-x`).                            |
| `rowFromEnd` | `number`                                                                                                                                                                                                                                                                                 | Which row the cell ends at, counting from the end (Bulma: `is-row-from-end-x`).    |
| `rowSpan`    | `number`                                                                                                                                                                                                                                                                                 | How many rows the cell will span (Bulma: `is-row-span-x`).                         |
| `className`  | `string`                                                                                                                                                                                                                                                                                 | Additional CSS class names.                                                        |
| `textColor`  | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | Text color.                                                                        |
| `color`      | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`                                                                                                                                                                                                          | Bulma color modifier for the cell.                                                 |
| `bgColor`    | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | Background color.                                                                  |
| `children`   | `React.ReactNode`                                                                                                                                                                                                                                                                        | Content to render inside the cell.                                                 |
| ...          | All Bulma helper and HTML props                                                                                                                                                                                                                                                          | (See [Helper Props](../helpers/usebulmaclasses))                                   |

---

## Usage

### Basic Usage

This example shows the `Cell` component used inside a `Grid`. Each `Cell` can contain any content, and the grid will automatically arrange the cells according to the available space and grid configuration.

```tsx live
<Grid>
  <Cell>
    <Notification color="primary">Basic Cell</Notification>
  </Cell>
  <Cell>
    <Notification color="info">Another Cell</Notification>
  </Cell>
</Grid>
```

---

### Column Start

Set the `colStart` prop to control which column a cell starts at. This is useful for manual placement and advanced grid layouts.

```tsx live
<Grid isFixed fixedCols={4}>
  <Cell>
    <Notification>Cell 1</Notification>
  </Cell>
  <Cell colStart={3}>
    <Notification color="primary">Cell 2</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 3</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 4</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 5</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 6</Notification>
  </Cell>
</Grid>
```

---

### Column From End

Use the `colFromEnd` prop to specify which column the cell should end at, counting from the last column. This allows for flexible layouts, especially in responsive designs.

```tsx live
<Grid isFixed fixedCols={4}>
  <Cell>
    <Notification>Cell 1</Notification>
  </Cell>
  <Cell colFromEnd={2}>
    <Notification color="primary">Cell 2</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 3</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 4</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 5</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 6</Notification>
  </Cell>
</Grid>
```

---

### Column Span

The `colSpan` prop defines how many columns a cell should span. This is useful for creating layouts where a cell needs to take up more space horizontally.

```tsx live
<Grid isFixed fixedCols={4}>
  <Cell>
    <Notification>Cell 1</Notification>
  </Cell>
  <Cell colSpan={2}>
    <Notification color="primary">Cell 2</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 3</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 4</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 5</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 6</Notification>
  </Cell>
</Grid>
```

---

### Row Start

Control the starting row of a cell using the `rowStart` prop. This can be used to create gaps or align items in specific rows.

```tsx live
<Grid isFixed fixedCols={4}>
  <Cell>
    <Notification>Cell 1</Notification>
  </Cell>
  <Cell rowStart={3}>
    <Notification color="primary">Cell 2</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 3</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 4</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 5</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 6</Notification>
  </Cell>
</Grid>
```

---

### Row Span

The `rowSpan` prop allows a cell to span multiple rows. This is particularly useful for creating complex layouts where certain content needs to be larger or span across multiple sections.

```tsx live
<Grid isFixed fixedCols={4}>
  <Cell>
    <Notification>Cell 1</Notification>
  </Cell>
  <Cell rowSpan={2}>
    <Notification color="primary" fullHeight>
      Cell 2
    </Notification>
  </Cell>
  <Cell>
    <Notification>Cell 3</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 4</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 5</Notification>
  </Cell>
  <Cell>
    <Notification>Cell 6</Notification>
  </Cell>
</Grid>
```

---

## Notes

- Use `Cell` inside a `Grid` for proper Bulma grid layout.
- You can combine all placement and span props for advanced grid arrangements.
- All Bulma utility helper props and HTML `` props are supported.

---

## See Also

- [Grid component](./grid.md)
- [Bulma Grid Documentation](https://bulma.io/documentation/grid/)
- [Storybook: Cell Story](https://bestax.io/storybook/?path=/story/grid-cell--column-start)

---

## Grid


## Overview

The `Grid` component provides Bulma's advanced CSS Grid layout for complex, modern layouts. It supports both responsive and fixed grid modes, gap and min column controls, fixed column counts (per breakpoint), and full color/background/utility helpers. Use with the [`Cell`](./cell.md) component for granular grid placement.

---

## Import

```tsx

```

---

## Props

| Prop                  | Type                                                                                                                                                                                                                                                                                     | Description                                                                        |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `isFixed`             | `boolean`                                                                                                                                                                                                                                                                                | Use a fixed grid layout (`.fixed-grid > .grid`).                                   |
| `gap`                 | 0-8                                                                                                                                                                                                                                                                                      | Main gap for grid (Bulma `is-gap-X`).                                              |
| `columnGap`           | 0-8                                                                                                                                                                                                                                                                                      | Column gap for grid (`is-column-gap-X`).                                           |
| `rowGap`              | 0-8                                                                                                                                                                                                                                                                                      | Row gap for grid (`is-row-gap-X`).                                                 |
| `minCol`              | 1-32                                                                                                                                                                                                                                                                                     | Minimum column width for the grid (`is-col-min-X`).                                |
| `fixedCols`           | 0-12, `'auto'`                                                                                                                                                                                                                                                                           | For fixed grids: explicit column count (`has-X-cols`), or `'auto'` for auto-count. |
| `fixedColsMobile`     | 0-12                                                                                                                                                                                                                                                                                     | For fixed grids: explicit column count for mobile.                                 |
| `fixedColsTablet`     | 0-12                                                                                                                                                                                                                                                                                     | For fixed grids: explicit column count for tablet.                                 |
| `fixedColsDesktop`    | 0-12                                                                                                                                                                                                                                                                                     | For fixed grids: explicit column count for desktop.                                |
| `fixedColsWidescreen` | 0-12                                                                                                                                                                                                                                                                                     | For fixed grids: explicit column count for widescreen.                             |
| `fixedColsFullhd`     | 0-12                                                                                                                                                                                                                                                                                     | For fixed grids: explicit column count for fullhd.                                 |
| `className`           | `string`                                                                                                                                                                                                                                                                                 | Additional CSS classes for the grid.                                               |
| `textColor`           | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | Text color.                                                                        |
| `color`               | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'`                                                                                                                                                                                                          | Bulma color modifier for the grid.                                                 |
| `bgColor`             | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | Background color.                                                                  |
| `children`            | `React.ReactNode`                                                                                                                                                                                                                                                                        | Children to render inside the grid (usually `Cell` components).                    |
| ...                   | All Bulma helper and HTML props                                                                                                                                                                                                                                                          | (See [Helper Props](../api/helpers/usebulmaclasses))                               |

---

## Usage

### Smart Grid

This example shows the `Grid` component rendering a set of `Cell` components. By default, the grid will automatically fit as many columns as possible based on the available space, making it ideal for responsive layouts without manual configuration.

```tsx live
<Grid>
  {[...Array(24)].map((_, i) => (
    <Cell key={i}>
      <Notification color="primary">Cell {i + 1}</Notification>
    </Cell>
  ))}
</Grid>
```

---

### Minimum Column Width

Set the `minCol` prop to control the minimum width of each column in the grid. This allows you to ensure that cells never shrink below a certain size, regardless of the screen width.

```tsx live
<Grid minCol={4}>
  {[...Array(24)].map((_, i) => (
    <Cell key={i}>
      <Notification color="primary" textSize="7">
        Cell {i + 1}
      </Notification>
    </Cell>
  ))}
</Grid>
```

You can control the minimum column width interactively; see the story for a demo.

---

### Gap

This example demonstrates the `gap` prop, which sets the spacing between grid cells. Adjust the value from 0 to 8 to control the amount of space between each cell.

```tsx live
<Grid gap={2}>
  {[...Array(24)].map((_, i) => (
    <Cell key={i}>
      <Notification color="primary">Cell {i + 1}</Notification>
    </Cell>
  ))}
</Grid>
```

---

### Column Gap

This example demonstrates the `columnGap` prop, which sets the horizontal spacing between columns in the grid. Adjust the value from 0 to 8 to control the space between columns only, without affecting row spacing.

```tsx live
<Grid columnGap={2}>
  {[...Array(24)].map((_, i) => (
    <Cell key={i}>
      <Notification color="primary">Cell {i + 1}</Notification>
    </Cell>
  ))}
</Grid>
```

---

### Row Gap

This example demonstrates the `rowGap` prop, which sets the vertical spacing between rows in the grid. Adjust the value from 0 to 8 to control the space between rows only, without affecting column spacing.

```tsx live
<Grid rowGap={2}>
  {[...Array(24)].map((_, i) => (
    <Cell key={i}>
      <Notification color="primary">Cell {i + 1}</Notification>
    </Cell>
  ))}
</Grid>
```

---

### Fixed Grid

This example shows how to enable fixed grid mode using the `isFixed` prop. In this mode, the grid uses a strict column layout, and you can control the number of columns with the `fixedCols` prop or its breakpoint variants.

```tsx live
<Grid isFixed>
  {[...Array(12)].map((_, i) => (
    <Cell key={i}>
      <Notification color="primary">Cell {i + 1}</Notification>
    </Cell>
  ))}
</Grid>
```

---

### Fixed Grid Cols

This example demonstrates the `fixedCols` prop, which specifies the number of columns in fixed grid mode. Here, the grid will always have exactly 4 columns, regardless of screen size.

```tsx live
<Grid isFixed fixedCols={4}>
  {[...Array(12)].map((_, i) => (
    <Cell key={i}>
      <Notification color="primary">Cell {i + 1}</Notification>
    </Cell>
  ))}
</Grid>
```

You can select the number of fixed columns interactively; see the story for a demo.

---

### Fixed Grid Cols By Breakpoint

This example demonstrates how to set different column counts for each breakpoint using the `fixedCols*` props. The grid will adjust the number of columns responsively as the screen size changes.

```tsx live
<Grid
  isFixed
  fixedCols={4}
  fixedColsMobile={4}
  fixedColsTablet={6}
  fixedColsDesktop={8}
  fixedColsWidescreen={10}
  fixedColsFullhd={12}
>
  {[...Array(12)].map((_, i) => (
    <Cell key={i}>
      <Notification color="primary">Cell {i + 1}</Notification>
    </Cell>
  ))}
</Grid>
```

---

### Fixed Grid Auto Count

This example shows how to use `fixedCols="auto"` to let the grid automatically determine the number of columns based on the content and available space. This is useful for dynamic layouts where the number of columns may change.

```tsx live
<Grid isFixed fixedCols="auto">
  {[...Array(16)].map((_, i) => (
    <Cell key={i}>
      <Notification color="primary">Cell {i + 1}</Notification>
    </Cell>
  ))}
</Grid>
```

---

## Cell Placement Examples

See [Cell documentation](./cell.md) for granular placement using `colStart`, `colFromEnd`, `colSpan`, `rowStart`, `rowSpan`, etc.

---

## Notes

- Use the `Cell` component as a child of `Grid` for individual cell placement and spanning.
- Fixed grid mode (`isFixed`) enables a strict column layout and enables `fixedCols`/`fixedCols*` props.
- All Bulma utility helper props are supported.

---

## See Also

- [Cell component](./cell.md)
- [Bulma Grid Documentation](https://bulma.io/documentation/grid/)
- [Storybook: Grid Story](https://bestax.io/storybook/?path=/story/grid-grid--smart-grid)

---

## classNames


## Overview

`classNames` is a utility function for conditionally joining class names together. It takes any number of arguments, which can be strings, numbers, arrays, or objects, and returns a space-separated string of unique class names. This is useful for dynamically constructing className values in React and other frameworks.

---

## Import

```tsx

```

---

## API

```ts
function classNames(
  ...args: (
    | string
    | number
    | undefined
    | null
    | false
    | Record<string, unknown>
    | unknown[]
  )[]
): string;
```

- Accepts any mix of:
  - `string` or `number`
  - Array of valid values (including nested arrays)
  - Object (`{ className: boolean }`), where keys are included if their value is truthy
  - Falsy values (`null`, `undefined`, `false`, `''`) are ignored

---

## Usage

### Basic Usage with Strings

```tsx live
function example() {
  return classNames('column', 'is-half', 'has-text-primary');
  // => 'column is-half has-text-primary'
}
```

---

### Combining Strings, Numbers, Falsy Values

```tsx live
function example() {
  return classNames('notification', 0, null, undefined, '', 'is-primary');
  // => 'notification 0 is-primary'
}
```

---

### Using Arrays

```tsx live
function example() {
  return classNames('button', ['is-primary', 'is-large']);
  // => 'button is-primary is-large'
}
```

---

### Using Objects

```tsx live
function example() {
  const hasError = true;
  return classNames('input', { 'is-danger': hasError, 'is-rounded': true });
  // If hasError = false: 'input is-rounded'
  // If hasError = true:  'input is-danger is-rounded'
}
```

---

### Nested Arrays and Objects

```tsx live
function example() {
  return classNames(
    'column',
    ['is-narrow', ['has-background-primary', { 'is-hidden': false }]],
    { 'is-size-4': true }
  );
  // => 'column is-narrow has-background-primary is-size-4'
}
```

---

### Removing Duplicate Class Names

```tsx live
function example() {
  return classNames('button', 'is-primary', 'button', [
    'is-primary',
    'is-large',
  ]);
  // => 'button is-primary is-large'
}
```

---

### Real Examples from Components

#### Columns and Column

```tsx live
function example() {
  const isGapless = true;
  const isMultiline = true;

  return classNames(
    'columns',
    { 'is-gapless': isGapless, 'is-multiline': isMultiline },
    ['has-background-light', 'is-vcentered']
  );
  // Example output: 'columns is-gapless is-multiline has-background-light is-vcentered'
}
```

#### Grid and Cell

```tsx live
function example() {
  const span = 2;

  return classNames('cell', { 'is-col-span-2': span === 2 }, [
    'has-text-primary',
    'is-row-span-3',
  ]);
  // Example output: 'cell is-col-span-2 has-text-primary is-row-span-3'
}
```

#### Dropdown

```tsx live
function example() {
  const active = true;
  const up = false;
  const right = true;
  const hoverable = false;
  const disabled = false;
  const className = 'my-custom-dropdown';

  return classNames(
    'dropdown',
    {
      'is-active': active,
      'is-up': up,
      'is-right': right,
      'is-hoverable': hoverable,
      'is-disabled': disabled,
    },
    className
  );
  // Possible output: 'dropdown is-active is-right my-custom-dropdown'
}
```

#### Card

```tsx live
function example() {
  const className = 'custom-class';
  const hasShadow = false;
  const bulmaHelperClasses = 'has-text-success';

  return classNames('card', className, bulmaHelperClasses, {
    'is-shadowless': !hasShadow,
  });
  // Example output: 'card custom-class has-text-success is-shadowless'
}
```

#### Menu

```tsx live
function example() {
  const className = 'sidebar-menu';
  const bulmaHelperClasses = 'has-background-light';

  return classNames('menu', className, bulmaHelperClasses);
  // Example output: 'menu sidebar-menu has-background-light'
}
```

#### Breadcrumb

```tsx live
function example() {
  const className = 'custom-breadcrumb';
  const bulmaHelperClasses = undefined;
  const alignment = 'centered';
  const separator = 'dot';
  const size = 'large';

  return classNames('breadcrumb', className, bulmaHelperClasses, {
    'is-centered': alignment === 'centered',
    'has-dot-separator': separator === 'dot',
    'is-large': size === 'large',
  });
  // Example output: 'breadcrumb custom-breadcrumb is-centered has-dot-separator is-large'
}
```

---

## Tips

- All falsy values are ignored.
- Array and object arguments can be nested arbitrarily deep.
- Duplicate class names are automatically removed.
- Useful for React's `className` prop, but can be used anywhere strings are needed.

---

## See Also

- [`useBulmaClasses`](./usebulmaclasses.md): Advanced Bulma helper class generator.
- [Bulma Documentation](https://bulma.io/documentation/)

---

## ConfigProvider


## Overview

The `ConfigProvider` component provides a React context for configuring global settings across all Bulma UI components. Currently, it supports setting a `classPrefix` that will be automatically applied to **all Bulma CSS classes**, including both main component classes (like `button`, `box`, `title`) and helper/modifier classes (like `is-primary`, `has-text-centered`, `m-4`), allowing you to namespace Bulma classes to avoid conflicts with other CSS frameworks or customize the class naming convention.

---

## Import

```tsx

```

---

## Props

| Prop          | Type                                                               | Description                                                                                                     |
| ------------- | ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| `children`    | `ReactNode`                                                        | The child components that will inherit the configuration settings.                                              |
| `classPrefix` | `string`                                                           | Optional prefix to add to all Bulma CSS classes. Useful for namespacing when integrating with other frameworks. |
| `iconLibrary` | `'fa' \| 'mdi' \| 'ion' \| 'material-icons' \| 'material-symbols'` | Default icon library for all child components.                                                                  |

---

## Hooks

### useConfig

Returns the current configuration context values.

```tsx
const { classPrefix } = useConfig();
```

### useClassPrefix

Convenience hook that returns just the classPrefix string (or empty string if not set).

```tsx
const classPrefix = useClassPrefix();
```

---

## Usage Examples

### Basic Usage with Class Prefix

Use `ConfigProvider` to add a prefix to all Bulma CSS classes within its scope:

```tsx

  ConfigProvider,
  Box,
  Title,
  Button,
  Notification,
} from '@allxsmith/bestax-bulma';

function App() {
  return (
    
      <Title size="3">Prefixed Bulma Components</Title>
      
        This demonstrates using ConfigProvider with{' '}
        <code>classPrefix="bestax-"</code> to add the "bestax-" prefix to all
        component CSS classes. This is useful when integrating Bulma with other
        CSS frameworks or when you need to namespace Bulma classes to avoid
        conflicts.
      

      <Notification color="info" mt="4">
        Tip: Open your browser's developer tools and inspect
        the DOM elements below. You'll see that all Bulma CSS classes have the
        "bestax-" prefix applied.
      </Notification>

      <ConfigProvider classPrefix="bestax-">
        <Box mt="4" p="4">
          {/* 
            This Box will have classes:
            - bestax-box (main class)
            - bestax-mt-4 (helper class)
            - bestax-p-4 (helper class)
          */}
          <Title size="4">Prefixed Components</Title>
          {/* 
            This Title will have classes:
            - bestax-title (main class)
            - bestax-is-4 (modifier class)
          */}
          
            All components inside this ConfigProvider will have their CSS
            classes prefixed with "bestax-". This allows you to use Bulma
            alongside other CSS frameworks without class name conflicts.
          
          <Button color="primary" mt="3" isRounded>
            {/* 
              This Button will have classes:
              - bestax-button (main class)
              - bestax-is-primary (modifier class)
              - bestax-is-rounded (modifier class)
              - bestax-mt-3 (helper class)
            */}
            Bulma-Prefixed Button
          </Button>
        </Box>
      </ConfigProvider>

      <Box mt="4" p="4">
        <Title size="4">Standard Components (No Prefix)</Title>
        
          Components outside the ConfigProvider use standard Bulma classes
          without any prefix.
        
        <Button color="info">Standard Button</Button>
      </Box>
    
  );
}
```

### Nested ConfigProviders

ConfigProviders can be nested, with inner providers overriding outer settings:

```tsx
function NestedExample() {
  return (
    <ConfigProvider classPrefix="outer-">
      <Box p="4">
        <Title>Outer Prefix (outer-)</Title>

        <ConfigProvider classPrefix="inner-">
          <Box p="4" mt="3">
            <Title>Inner Prefix (inner-)</Title>
            <Button color="primary">Inner Button</Button>
          </Box>
        </ConfigProvider>

        <Button color="info" mt="3">
          Outer Button
        </Button>
      </Box>
    </ConfigProvider>
  );
}
```

### Using Configuration in Custom Components

Access the configuration in your own components using the `useConfig` hook:

```tsx

function CustomComponent() {
  const { classPrefix } = useConfig();
  const className = classPrefix
    ? `${classPrefix}custom-component`
    : 'custom-component';

  return (
    
      My custom component with prefix: {classPrefix || 'none'}
    
  );
}
```

---

## Use Cases

### Framework Integration

When integrating Bulma with other CSS frameworks like Bootstrap or Tailwind CSS:

```tsx
<ConfigProvider classPrefix="bestax-">
  <App />
</ConfigProvider>
```

This ensures all Bulma classes are prefixed with `bestax-`, preventing conflicts with other framework classes.

### Multi-tenant Applications

For applications that need to support different styling themes or brands:

```tsx
<ConfigProvider classPrefix={`${tenantName}-`}>
  <TenantApp />
</ConfigProvider>
```

### Component Library Wrapping

When wrapping Bulma UI components in your own component library:

```tsx
<ConfigProvider classPrefix="mylib-">
  <MyComponentLibrary />
</ConfigProvider>
```

---

## Notes

- The `classPrefix` is applied to **all Bulma classes**:
  - Main component classes (e.g., `button` → `bestax-button`, `box` → `bestax-box`)
  - Helper/modifier classes (e.g., `is-primary` → `bestax-is-primary`, `has-text-centered` → `bestax-has-text-centered`)
  - Spacing classes (e.g., `m-4` → `bestax-m-4`, `p-2` → `bestax-p-2`)
  - All other Bulma utility classes
- Changes to the `classPrefix` will affect all child components immediately
- If no `classPrefix` is provided, components use standard Bulma class names
- The ConfigProvider must wrap all components that should inherit the configuration

---

## TypeScript Support

Full TypeScript support is included:

```tsx
interface ConfigContextProps {
  classPrefix?: string;
  iconLibrary?: 'fa' | 'mdi' | 'ion' | 'material-icons' | 'material-symbols';
}

interface ConfigProviderProps {
  children: ReactNode;
  classPrefix?: string;
  iconLibrary?: 'fa' | 'mdi' | 'ion' | 'material-icons' | 'material-symbols';
}
```

---

## Theme


## Overview

The `Theme` component provides a powerful way to customize Bulma's appearance using CSS custom properties (CSS variables). It allows you to override Bulma's design tokens like colors, spacing, typography, and other visual properties either globally or locally within specific component trees. The Theme component supports both CSS variable injection via props and direct CSS variable objects.

---

## Import

```tsx

```

---

## Props

| Prop        | Type                            | Description                                                                                                                                                                                                                                               |
| ----------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `children`  | `ReactNode`                     | The child components to apply the theme to.                                                                                                                                                                                                               |
| `className` | `string`                        | Additional CSS classes for the theme wrapper.                                                                                                                                                                                                             |
| `isRoot`    | `boolean`                       | When `true`, applies CSS variables globally at `:root` level. When `false` (default), applies variables only to the wrapper div.                                                                                                                          |
| `colorMode` | `'light' \| 'dark' \| 'system'` | Sets Bulma's light/dark scheme by writing the `data-theme` attribute on `<html>`. Always global (even on a scoped `Theme`). `'system'` removes the attribute so Bulma follows the OS `prefers-color-scheme`. Omit to leave the current setting untouched. |
| `bulmaVars` | `Record<string, string>`        | Object containing CSS custom properties as key-value pairs (e.g., `{'--bulma-primary-h': '210'}`).                                                                                                                                                        |

### CSS Variable Props

The Theme component accepts individual CSS variable props that correspond to Bulma's design tokens. These props are automatically converted to their corresponding CSS custom properties (e.g., `primaryH` → `--bulma-primary-h`).

#### Scheme Variables

| Prop                     | Type     | Description                                       | CSS Variable                        |
| ------------------------ | -------- | ------------------------------------------------- | ----------------------------------- |
| `schemeH`                | `string` | Base hue for the color scheme (0-360)             | `--bulma-scheme-h`                  |
| `schemeS`                | `string` | Base saturation for the color scheme (percentage) | `--bulma-scheme-s`                  |
| `lightL`                 | `string` | Lightness value for light backgrounds             | `--bulma-light-l`                   |
| `lightInvertL`           | `string` | Inverted lightness for light backgrounds          | `--bulma-light-invert-l`            |
| `darkL`                  | `string` | Lightness value for dark backgrounds              | `--bulma-dark-l`                    |
| `darkInvertL`            | `string` | Inverted lightness for dark backgrounds           | `--bulma-dark-invert-l`             |
| `softL`                  | `string` | Lightness value for soft colors                   | `--bulma-soft-l`                    |
| `boldL`                  | `string` | Lightness value for bold colors                   | `--bulma-bold-l`                    |
| `softInvertL`            | `string` | Inverted lightness for soft colors                | `--bulma-soft-invert-l`             |
| `boldInvertL`            | `string` | Inverted lightness for bold colors                | `--bulma-bold-invert-l`             |
| `hoverBackgroundLDelta`  | `string` | Lightness delta for hover background states       | `--bulma-hover-background-l-delta`  |
| `activeBackgroundLDelta` | `string` | Lightness delta for active background states      | `--bulma-active-background-l-delta` |
| `hoverBorderLDelta`      | `string` | Lightness delta for hover border states           | `--bulma-hover-border-l-delta`      |
| `activeBorderLDelta`     | `string` | Lightness delta for active border states          | `--bulma-active-border-l-delta`     |
| `hoverColorLDelta`       | `string` | Lightness delta for hover text color states       | `--bulma-hover-color-l-delta`       |
| `activeColorLDelta`      | `string` | Lightness delta for active text color states      | `--bulma-active-color-l-delta`      |
| `hoverShadowADelta`      | `string` | Alpha delta for hover shadow states               | `--bulma-hover-shadow-a-delta`      |
| `activeShadowADelta`     | `string` | Alpha delta for active shadow states              | `--bulma-active-shadow-a-delta`     |

#### Color Variables

| Prop       | Type     | Description                           | CSS Variable        |
| ---------- | -------- | ------------------------------------- | ------------------- |
| `primaryH` | `string` | Primary color hue (0-360)             | `--bulma-primary-h` |
| `primaryS` | `string` | Primary color saturation (percentage) | `--bulma-primary-s` |
| `primaryL` | `string` | Primary color lightness (percentage)  | `--bulma-primary-l` |
| `linkH`    | `string` | Link color hue (0-360)                | `--bulma-link-h`    |
| `linkS`    | `string` | Link color saturation (percentage)    | `--bulma-link-s`    |
| `linkL`    | `string` | Link color lightness (percentage)     | `--bulma-link-l`    |
| `infoH`    | `string` | Info color hue (0-360)                | `--bulma-info-h`    |
| `infoS`    | `string` | Info color saturation (percentage)    | `--bulma-info-s`    |
| `infoL`    | `string` | Info color lightness (percentage)     | `--bulma-info-l`    |
| `successH` | `string` | Success color hue (0-360)             | `--bulma-success-h` |
| `successS` | `string` | Success color saturation (percentage) | `--bulma-success-s` |
| `successL` | `string` | Success color lightness (percentage)  | `--bulma-success-l` |
| `warningH` | `string` | Warning color hue (0-360)             | `--bulma-warning-h` |
| `warningS` | `string` | Warning color saturation (percentage) | `--bulma-warning-s` |
| `warningL` | `string` | Warning color lightness (percentage)  | `--bulma-warning-l` |
| `dangerH`  | `string` | Danger color hue (0-360)              | `--bulma-danger-h`  |
| `dangerS`  | `string` | Danger color saturation (percentage)  | `--bulma-danger-s`  |
| `dangerL`  | `string` | Danger color lightness (percentage)   | `--bulma-danger-l`  |

#### Complete CSS Variables List

The Theme component supports all 500+ Bulma CSS variables through the `bulmaVars` prop and individual props:

**Typography Variables:**

- `--bulma-family-primary`, `--bulma-family-secondary`, `--bulma-family-code`
- `--bulma-size-small`, `--bulma-size-normal`, `--bulma-size-medium`, `--bulma-size-large`
- `--bulma-weight-light`, `--bulma-weight-normal`, `--bulma-weight-medium`, `--bulma-weight-semibold`, `--bulma-weight-bold`, `--bulma-weight-extrabold`
- `--bulma-body-background-color`, `--bulma-body-size`, `--bulma-body-min-width`, `--bulma-body-rendering`
- `--bulma-body-family`, `--bulma-body-overflow-x`, `--bulma-body-overflow-y`, `--bulma-body-color`
- `--bulma-body-font-size`, `--bulma-body-weight`, `--bulma-body-line-height`
- `--bulma-code-family`, `--bulma-code-padding`, `--bulma-code-weight`, `--bulma-code-size`
- `--bulma-small-font-size`, `--bulma-hr-background-color`, `--bulma-hr-height`, `--bulma-hr-margin`
- `--bulma-strong-color`, `--bulma-strong-weight`, `--bulma-pre-font-size`, `--bulma-pre-padding`, `--bulma-pre-code-font-size`

**Layout & Spacing Variables:**

- `--bulma-block-spacing`, `--bulma-duration`, `--bulma-easing`, `--bulma-speed`
- `--bulma-radius-small`, `--bulma-radius`, `--bulma-radius-medium`, `--bulma-radius-large`, `--bulma-radius-rounded`
- `--bulma-arrow-color`, `--bulma-loading-color`
- `--bulma-column-gap`, `--bulma-grid-gap`, `--bulma-grid-column-count`, `--bulma-grid-column-min`
- `--bulma-grid-cell-column-span`, `--bulma-grid-cell-column-start`

**Box Variables:**

- `--bestax-box-background-color`, `--bestax-box-color`, `--bestax-box-radius`, `--bestax-box-shadow`
- `--bestax-box-padding`, `--bestax-box-link-hover-shadow`, `--bestax-box-link-active-shadow`

**Breadcrumb Variables:**

- `--bulma-breadcrumb-item-color`, `--bulma-breadcrumb-item-hover-color`, `--bulma-breadcrumb-item-active-color`
- `--bulma-breadcrumb-item-padding-vertical`, `--bulma-breadcrumb-item-padding-horizontal`
- `--bulma-breadcrumb-item-separator-color`

**Card Variables:**

- `--bestax-card-color`, `--bestax-card-background-color`, `--bestax-card-shadow`, `--bestax-card-radius`
- `--bestax-card-header-background-color`, `--bestax-card-header-color`, `--bestax-card-header-padding`
- `--bestax-card-header-shadow`, `--bestax-card-header-weight`
- `--bestax-card-content-background-color`, `--bestax-card-content-padding`
- `--bestax-card-footer-background-color`, `--bestax-card-footer-border-top`, `--bestax-card-footer-padding`
- `--bestax-card-media-margin`

**Dropdown Variables:**

- `--bulma-dropdown-menu-min-width`, `--bulma-dropdown-content-background-color`
- `--bulma-dropdown-content-offset`, `--bulma-dropdown-content-padding-bottom`
- `--bulma-dropdown-content-padding-top`, `--bulma-dropdown-content-radius`
- `--bulma-dropdown-content-shadow`, `--bulma-dropdown-content-z`
- `--bulma-dropdown-item-h`, `--bulma-dropdown-item-s`, `--bulma-dropdown-item-l`
- `--bulma-dropdown-item-background-l`, `--bulma-dropdown-item-background-l-delta`
- `--bulma-dropdown-item-hover-background-l-delta`, `--bulma-dropdown-item-active-background-l-delta`
- `--bulma-dropdown-item-color-l`, `--bulma-dropdown-item-selected-h`
- `--bulma-dropdown-item-selected-s`, `--bulma-dropdown-item-selected-l`
- `--bulma-dropdown-item-selected-background-l`, `--bulma-dropdown-item-selected-color-l`
- `--bulma-dropdown-divider-background-color`

**Input Variables:**

- `--bulma-input-h`, `--bulma-input-s`, `--bulma-input-l`, `--bulma-input-border-style`
- `--bulma-input-border-l`, `--bulma-input-border-l-delta`, `--bulma-input-hover-border-l-delta`
- `--bulma-input-active-border-l-delta`, `--bulma-input-focus-h`, `--bulma-input-focus-s`
- `--bulma-input-focus-l`, `--bulma-input-focus-shadow-size`, `--bulma-input-focus-shadow-alpha`
- `--bulma-input-color-l`, `--bulma-input-background-l`, `--bulma-input-background-l-delta`
- `--bulma-input-height`, `--bulma-input-shadow`, `--bulma-input-placeholder-color`
- `--bulma-input-disabled-color`, `--bulma-input-disabled-background-color`
- `--bulma-input-disabled-border-color`, `--bulma-input-disabled-placeholder-color`
- `--bulma-input-arrow`, `--bulma-input-icon-color`, `--bulma-input-icon-hover-color`
- `--bulma-input-icon-focus-color`, `--bulma-input-radius`

**Menu Variables:**

- `--bulma-menu-item-h`, `--bulma-menu-item-s`, `--bulma-menu-item-l`
- `--bulma-menu-item-background-l`, `--bulma-menu-item-background-l-delta`
- `--bulma-menu-item-hover-background-l-delta`, `--bulma-menu-item-active-background-l-delta`
- `--bulma-menu-item-color-l`, `--bulma-menu-item-radius`
- `--bulma-menu-item-selected-h`, `--bulma-menu-item-selected-s`, `--bulma-menu-item-selected-l`
- `--bulma-menu-item-selected-background-l`, `--bulma-menu-item-selected-color-l`
- `--bulma-menu-list-border-left`, `--bulma-menu-list-line-height`, `--bulma-menu-list-link-padding`
- `--bulma-menu-nested-list-margin`, `--bulma-menu-nested-list-padding-left`
- `--bulma-menu-label-color`, `--bulma-menu-label-font-size`, `--bulma-menu-label-letter-spacing`
- `--bulma-menu-label-spacing`

**Message Variables:**

- `--bulma-message-h`, `--bulma-message-s`, `--bulma-message-background-l`
- `--bulma-message-border-l`, `--bulma-message-border-l-delta`, `--bulma-message-border-style`
- `--bulma-message-border-width`, `--bulma-message-color-l`, `--bulma-message-radius`
- `--bulma-message-header-weight`, `--bulma-message-header-padding`, `--bulma-message-header-radius`
- `--bulma-message-header-body-border-width`, `--bulma-message-header-background-l`
- `--bulma-message-header-color-l`, `--bulma-message-body-border-width`
- `--bulma-message-body-color`, `--bulma-message-body-padding`, `--bulma-message-body-radius`
- `--bulma-message-body-pre-code-background-color`

**Modal Variables:**

- `--bulma-modal-z`, `--bulma-modal-background-background-color`, `--bulma-modal-content-width`
- `--bulma-modal-content-margin-mobile`, `--bulma-modal-content-spacing-mobile`
- `--bulma-modal-content-spacing-tablet`, `--bulma-modal-close-dimensions`
- `--bulma-modal-close-right`, `--bulma-modal-close-top`, `--bulma-modal-card-spacing`
- `--bulma-modal-card-head-background-color`, `--bulma-modal-card-head-padding`
- `--bulma-modal-card-head-radius`, `--bulma-modal-card-title-color`
- `--bulma-modal-card-title-line-height`, `--bulma-modal-card-title-size`
- `--bulma-modal-card-foot-background-color`, `--bulma-modal-card-foot-radius`
- `--bulma-modal-card-body-background-color`, `--bulma-modal-card-body-padding`

**Navbar Variables:**

- `--bulma-navbar-h`, `--bulma-navbar-s`, `--bulma-navbar-l`, `--bulma-navbar-background-color`
- `--bulma-navbar-box-shadow-size`, `--bulma-navbar-box-shadow-color`
- `--bulma-navbar-padding-vertical`, `--bulma-navbar-padding-horizontal`
- `--bulma-navbar-z`, `--bulma-navbar-fixed-z`, `--bulma-navbar-item-background-a`
- `--bulma-navbar-item-background-l`, `--bulma-navbar-item-background-l-delta`
- `--bulma-navbar-item-hover-background-l-delta`, `--bulma-navbar-item-active-background-l-delta`
- `--bulma-navbar-item-color-l`, `--bulma-navbar-item-selected-h`
- `--bulma-navbar-item-selected-s`, `--bulma-navbar-item-selected-l`
- `--bulma-navbar-item-selected-background-l`, `--bulma-navbar-item-selected-color-l`
- `--bulma-navbar-item-img-max-height`, `--bulma-navbar-burger-color`
- `--bulma-navbar-tab-hover-background-color`, `--bulma-navbar-tab-hover-border-bottom-color`
- `--bulma-navbar-tab-active-color`, `--bulma-navbar-tab-active-background-color`
- `--bulma-navbar-tab-active-border-bottom-color`, `--bulma-navbar-tab-active-border-bottom-style`
- `--bulma-navbar-tab-active-border-bottom-width`, `--bulma-navbar-dropdown-background-color`
- `--bulma-navbar-dropdown-border-l`, `--bulma-navbar-dropdown-border-color`
- `--bulma-navbar-dropdown-border-style`, `--bulma-navbar-dropdown-border-width`
- `--bulma-navbar-dropdown-offset`, `--bulma-navbar-dropdown-arrow`
- `--bulma-navbar-dropdown-radius`, `--bulma-navbar-dropdown-z`
- `--bulma-navbar-dropdown-boxed-radius`, `--bulma-navbar-dropdown-boxed-shadow`
- `--bulma-navbar-dropdown-item-h`, `--bulma-navbar-dropdown-item-s`
- `--bulma-navbar-dropdown-item-l`, `--bulma-navbar-dropdown-item-background-l`
- `--bulma-navbar-dropdown-item-color-l`, `--bulma-navbar-divider-background-l`
- `--bulma-navbar-divider-height`, `--bulma-navbar-bottom-box-shadow-size`

**Notification Variables:**

- `--bestax-notification-h`, `--bestax-notification-s`, `--bestax-notification-background-l`
- `--bestax-notification-color-l`, `--bestax-notification-code-background-color`
- `--bestax-notification-radius`, `--bestax-notification-padding`

**Pagination Variables:**

- `--bulma-pagination-margin`, `--bulma-pagination-min-width`
- `--bulma-pagination-item-h`, `--bulma-pagination-item-s`, `--bulma-pagination-item-l`
- `--bulma-pagination-item-background-l-delta`, `--bulma-pagination-item-hover-background-l-delta`
- `--bulma-pagination-item-active-background-l-delta`, `--bulma-pagination-item-border-style`
- `--bulma-pagination-item-border-width`, `--bulma-pagination-item-border-l`
- `--bulma-pagination-item-border-l-delta`, `--bulma-pagination-item-hover-border-l-delta`
- `--bulma-pagination-item-active-border-l-delta`, `--bulma-pagination-item-focus-border-l-delta`
- `--bulma-pagination-item-color-l`, `--bulma-pagination-item-font-size`
- `--bulma-pagination-item-margin`, `--bulma-pagination-item-padding-left`
- `--bulma-pagination-item-padding-right`, `--bulma-pagination-item-outer-shadow-h`
- `--bulma-pagination-item-outer-shadow-s`, `--bulma-pagination-item-outer-shadow-l`
- `--bulma-pagination-item-outer-shadow-a`, `--bulma-pagination-nav-padding-left`
- `--bulma-pagination-nav-padding-right`, `--bulma-pagination-disabled-color`
- `--bulma-pagination-disabled-background-color`, `--bulma-pagination-disabled-border-color`
- `--bulma-pagination-current-color`, `--bulma-pagination-current-background-color`
- `--bulma-pagination-current-border-color`, `--bulma-pagination-ellipsis-color`
- `--bulma-pagination-shadow-inset`, `--bulma-pagination-selected-item-h`
- `--bulma-pagination-selected-item-s`, `--bulma-pagination-selected-item-l`
- `--bulma-pagination-selected-item-background-l`, `--bulma-pagination-selected-item-border-l`
- `--bulma-pagination-selected-item-color-l`

**Panel Variables:**

- `--bulma-panel-margin`, `--bulma-panel-item-border`, `--bulma-panel-radius`, `--bulma-panel-shadow`
- `--bulma-panel-heading-line-height`, `--bulma-panel-heading-padding`, `--bulma-panel-heading-radius`
- `--bulma-panel-heading-size`, `--bulma-panel-heading-weight`, `--bulma-panel-tabs-font-size`
- `--bulma-panel-tab-border-bottom-color`, `--bulma-panel-tab-border-bottom-style`
- `--bulma-panel-tab-border-bottom-width`, `--bulma-panel-tab-active-color`
- `--bulma-panel-list-item-color`, `--bulma-panel-list-item-hover-color`
- `--bulma-panel-block-color`, `--bulma-panel-block-hover-background-color`
- `--bulma-panel-block-active-border-left-color`, `--bulma-panel-block-active-color`
- `--bulma-panel-block-active-icon-color`, `--bulma-panel-icon-color`

**Progress Variables:**

- `--bulma-progress-border-radius`, `--bulma-progress-bar-background-color`
- `--bulma-progress-value-background-color`, `--bulma-progress-indeterminate-duration`

**Skeleton Variables:**

- `--bulma-skeleton-background`, `--bulma-skeleton-radius`, `--bulma-skeleton-block-min-height`
- `--bulma-skeleton-lines-gap`, `--bulma-skeleton-line-height`

**Table Variables:**

- `--bulma-table-color`, `--bulma-table-background-color`, `--bulma-table-cell-border-color`
- `--bulma-table-cell-border-style`, `--bulma-table-cell-border-width`, `--bulma-table-cell-padding`
- `--bulma-table-cell-heading-color`, `--bulma-table-cell-text-align`
- `--bulma-table-head-cell-border-width`, `--bulma-table-head-cell-color`
- `--bulma-table-foot-cell-border-width`, `--bulma-table-foot-cell-color`
- `--bulma-table-head-background-color`, `--bulma-table-body-background-color`
- `--bulma-table-foot-background-color`, `--bulma-table-row-hover-background-color`
- `--bulma-table-row-active-background-color`, `--bulma-table-row-active-color`
- `--bulma-table-striped-row-even-background-color`, `--bulma-table-striped-row-even-hover-background-color`

**Tabs Variables:**

- `--bulma-tabs-border-bottom-color`, `--bulma-tabs-border-bottom-style`, `--bulma-tabs-border-bottom-width`
- `--bulma-tabs-link-color`, `--bulma-tabs-link-hover-border-bottom-color`, `--bulma-tabs-link-hover-color`
- `--bulma-tabs-link-active-border-bottom-color`, `--bulma-tabs-link-active-color`, `--bulma-tabs-link-padding`
- `--bulma-tabs-boxed-link-radius`, `--bulma-tabs-boxed-link-hover-background-color`
- `--bulma-tabs-boxed-link-hover-border-bottom-color`, `--bulma-tabs-boxed-link-active-background-color`
- `--bulma-tabs-boxed-link-active-border-color`, `--bulma-tabs-boxed-link-active-border-bottom-color`
- `--bulma-tabs-toggle-link-border-color`, `--bulma-tabs-toggle-link-border-style`
- `--bulma-tabs-toggle-link-border-width`, `--bulma-tabs-toggle-link-hover-background-color`
- `--bulma-tabs-toggle-link-hover-border-color`, `--bulma-tabs-toggle-link-radius`
- `--bulma-tabs-toggle-link-active-background-color`, `--bulma-tabs-toggle-link-active-border-color`
- `--bulma-tabs-toggle-link-active-color`

**Tag Variables:**

- `--bulma-tag-h`, `--bulma-tag-s`, `--bulma-tag-background-l`, `--bulma-tag-background-l-delta`
- `--bulma-tag-hover-background-l-delta`, `--bulma-tag-active-background-l-delta`
- `--bulma-tag-color-l`, `--bulma-tag-radius`, `--bulma-tag-delete-margin`

**Title & Subtitle Variables:**

- `--bestax-title-color`, `--bestax-title-family`, `--bestax-title-size`, `--bestax-title-weight`
- `--bestax-title-line-height`, `--bestax-title-strong-color`, `--bestax-title-strong-weight`
- `--bestax-title-sub-size`, `--bestax-title-sup-size`
- `--bulma-subtitle-color`, `--bulma-subtitle-family`, `--bulma-subtitle-size`, `--bulma-subtitle-weight`
- `--bulma-subtitle-line-height`, `--bulma-subtitle-strong-color`, `--bulma-subtitle-strong-weight`

**Content Variables:**

- `--bulma-content-heading-color`, `--bulma-content-heading-weight`, `--bulma-content-heading-line-height`
- `--bulma-content-block-margin-bottom`, `--bulma-content-blockquote-background-color`
- `--bulma-content-blockquote-border-left`, `--bulma-content-blockquote-padding`, `--bulma-content-pre-padding`
- `--bulma-content-table-cell-border`, `--bulma-content-table-cell-border-width`
- `--bulma-content-table-cell-padding`, `--bulma-content-table-cell-heading-color`
- `--bulma-content-table-head-cell-border-width`, `--bulma-content-table-head-cell-color`
- `--bulma-content-table-body-last-row-cell-border-bottom-width`
- `--bulma-content-table-foot-cell-border-width`, `--bulma-content-table-foot-cell-color`

**Control Variables:**

- `--bulma-control-radius`, `--bulma-control-radius-small`, `--bulma-control-border-width`
- `--bulma-control-height`, `--bulma-control-line-height`, `--bulma-control-padding-vertical`
- `--bulma-control-padding-horizontal`, `--bulma-control-size`, `--bulma-control-focus-shadow-l`

**Delete Variables:**

- `--bulma-delete-dimensions`, `--bulma-delete-background-l`, `--bulma-delete-background-alpha`
- `--bulma-delete-color`

**File Variables:**

- `--bulma-file-radius`, `--bulma-file-name-border-color`, `--bulma-file-name-border-style`
- `--bulma-file-name-border-width`, `--bulma-file-name-max-width`
- `--bulma-file-h`, `--bulma-file-s`, `--bulma-file-background-l`, `--bulma-file-background-l-delta`
- `--bulma-file-hover-background-l-delta`, `--bulma-file-active-background-l-delta`
- `--bulma-file-border-l`, `--bulma-file-border-l-delta`, `--bulma-file-hover-border-l-delta`
- `--bulma-file-active-border-l-delta`, `--bulma-file-cta-color-l`, `--bulma-file-name-color-l`
- `--bulma-file-color-l-delta`, `--bulma-file-hover-color-l-delta`, `--bulma-file-active-color-l-delta`

**Footer Variables:**

- `--bulma-footer-background-color`, `--bulma-footer-color`, `--bulma-footer-padding`

**Hero Variables:**

- `--bulma-hero-body-padding`, `--bulma-hero-body-padding-tablet`, `--bulma-hero-body-padding-small`
- `--bulma-hero-body-padding-medium`, `--bulma-hero-body-padding-large`

**Icon Variables:**

- `--bulma-icon-dimensions`, `--bulma-icon-dimensions-small`, `--bulma-icon-dimensions-medium`
- `--bulma-icon-dimensions-large`, `--bulma-icon-text-spacing`

**Media Variables:**

- `--bulma-media-border-color`, `--bulma-media-border-size`, `--bulma-media-spacing`
- `--bulma-media-spacing-large`, `--bulma-media-content-spacing`, `--bulma-media-level-1-spacing`
- `--bulma-media-level-1-content-spacing`, `--bulma-media-level-2-spacing`

**Section Variables:**

- `--bulma-section-padding`, `--bulma-section-padding-desktop`, `--bulma-section-padding-medium`
- `--bulma-section-padding-large`

**Burger Variables:**

- `--bulma-burger-h`, `--bulma-burger-s`, `--bulma-burger-l`, `--bulma-burger-border-radius`
- `--bulma-burger-gap`, `--bulma-burger-item-height`, `--bulma-burger-item-width`

The Theme component also supports all [Bulma helper class props](./usebulmaclasses.md) for styling the wrapper element.

---

## Usage

### Basic Theme Customization

```tsx
function BasicThemeCustomization() {
  return (
    <Theme primaryH="270" primaryS="100%" primaryL="50%">
      <Box p="4">
        <Button color="primary">Purple Primary Button</Button>
      </Box>
    </Theme>
  );
}
```

### Global Theme (Root Level)

```tsx
function GlobalTheme() {
  return (
    <Theme isRoot={true} primaryH="270" primaryS="100%" primaryL="50%">
      
        <Button color="primary">Global Purple Theme</Button>
        <Button color="info">Info Button</Button>
      
    </Theme>
  );
}
```

### Dark Mode

The `colorMode` prop sets Bulma's `data-theme` on `<html>`, flipping the light/dark scheme globally.
Use `'system'` to follow the OS preference.

```tsx

function App() {
  const [mode, setMode] = useState<'light' | 'dark' | 'system'>('system');
  return (
    <Theme isRoot colorMode={mode}>
      <Button color="primary" onClick={() => setMode('dark')}>
        Dark
      </Button>
      <Button color="primary" onClick={() => setMode('light')}>
        Light
      </Button>
      <Button onClick={() => setMode('system')}>System</Button>
    </Theme>
  );
}
```

### Local Theme (Component Level)

```tsx
function LocalTheme() {
  return (
    
      <Button color="primary">Standard Primary</Button>

      <Theme primaryH="120" primaryS="100%" primaryL="40%">
        <Button color="primary">Green Primary</Button>
      </Theme>

      <Button color="primary">Standard Primary Again</Button>
    
  );
}
```

### Using CSS Variables Object

```tsx
function SunsetTheme() {
  const sunsetTheme = {
    '--bulma-scheme-h': '18',
    '--bulma-scheme-s': '90%',
    '--bulma-light-l': '85%',
    '--bulma-dark-l': '20%',
    '--bulma-primary-h': '25',
    '--bulma-primary-s': '85%',
    '--bulma-primary-l': '55%',
  };

  return (
    <Theme bulmaVars={sunsetTheme} isRoot>
      <Box p="4">
        <Title>Sunset Theme</Title>
        <Button color="primary">Sunset Button</Button>
        <Button color="info">Info Button</Button>
      </Box>
    </Theme>
  );
}
```

### Advanced CSS Variables Usage

```tsx
function TypographyTheme() {
  const typographyTheme = {
    '--bulma-family-primary': '"Helvetica Neue", sans-serif',
    '--bulma-family-code': '"Fira Code", monospace',
    '--bulma-size-normal': '16px',
    '--bulma-weight-bold': '700',
    '--bestax-title-color': 'hsl(0, 0%, 21%)',
    '--bulma-subtitle-color': 'hsl(0, 0%, 48%)',
  };

  return (
    <Theme bulmaVars={typographyTheme}>
      <Title>Custom Typography</Title>
      <Subtitle>With custom fonts and weights</Subtitle>
    </Theme>
  );
}
```

```tsx
function CustomButtonTheme() {
  const customButton = {
    '--bestax-button-border-radius': '12px',
    '--bestax-button-padding-vertical': '0.75rem',
    '--bestax-button-padding-horizontal': '1.5rem',
    '--bestax-button-focus-box-shadow-size': '0 0 0 0.2rem',
    '--bestax-button-focus-box-shadow-color': 'rgba(72, 95, 199, 0.25)',
  };

  return (
    <Theme bulmaVars={customButton}>
      <Button color="primary">Custom Styled Button</Button>
    </Theme>
  );
}
```

```tsx
function SpacingTheme() {
  const spacingTheme = {
    '--bulma-block-spacing': '2rem',
    '--bulma-column-gap': '1rem',
    '--bulma-section-padding': '4rem 1.5rem',
    '--bestax-box-padding': '2rem',
    '--bestax-card-content-padding': '2rem',
  };

  return (
    <Theme bulmaVars={spacingTheme}>
      <Section>
        <Columns>
          <Column>
            <Box>Content with custom spacing</Box>
          </Column>
          <Column>
            <Card>
              <CardContent>Custom card padding</CardContent>
            </Card>
          </Column>
        </Columns>
      </Section>
    </Theme>
  );
}
```

### Complete Color Scheme

```tsx
function ForestTheme() {
  const forestScheme = {
    schemeH: '150', // forest green hue
    schemeS: '50%',
    lightL: '80%',
    lightInvertL: '20%',
    darkL: '18%',
    darkInvertL: '85%',
    softL: '55%',
    boldL: '35%',
    primaryH: '160',
    primaryS: '60%',
    primaryL: '45%',
    linkH: '155',
    linkS: '65%',
    linkL: '40%',
    successH: '120',
    successS: '70%',
    successL: '45%',
    warningH: '45',
    warningS: '85%',
    warningL: '55%',
    dangerH: '355',
    dangerS: '75%',
    dangerL: '50%',
    hoverBackgroundLDelta: '4%',
    activeBackgroundLDelta: '8%',
  };

  return (
    <Theme {...forestScheme} isRoot>
      <Box p="4">
        <Title>Forest Theme</Title>
        <Button color="primary">Forest Primary</Button>
        <Button color="success">Success</Button>
        <Button color="info">Info</Button>
        <Button color="warning">Warning</Button>
        <Button color="danger">Danger</Button>
      </Box>
    </Theme>
  );
}
```

````

### Theme with Styling

```tsx
function StyledTheme() {
  return (
    <Theme
      className="custom-theme-wrapper"
      primaryH="45"
      primaryS="100%"
      primaryL="50%"
      p="5"
      m="3"
      textAlign="centered"
      backgroundColor="light"
    >
      <Title>Styled Theme Container</Title>
      <Button color="primary">Styled Button</Button>
    </Theme>
  );
}
````

### Nested Themes

```tsx
function NestedThemes() {
  return (
    <Theme primaryH="210" primaryS="60%" primaryL="45%" p="4">
      <Title>Outer Theme (Blue)</Title>
      <Button color="primary">Blue Primary</Button>

      <Theme
        primaryH="120"
        primaryS="70%"
        primaryL="40%"
        p="3"
        mt="4"
        backgroundColor="light"
      >
        <Title size="4">Inner Theme (Green)</Title>
        <Button color="primary">Green Primary</Button>
      </Theme>

      <Button color="primary" mt="3">
        Blue Primary Again
      </Button>
    </Theme>
  );
}
```

### Theme with ConfigProvider

```tsx
function PrefixedTheme() {
  return (
    <ConfigProvider classPrefix="bestax-">
      <Theme primaryH="300" primaryS="80%" primaryL="50%" isRoot>
        <Button color="primary">Prefixed & Themed Button</Button>
      </Theme>
    </ConfigProvider>
  );
}
```

---

## Best Practices

### Global vs Local Themes

- Use `isRoot={true}` for application-wide themes that should affect all components
- Use local themes (default `isRoot={false}`) for component-specific styling or theme variations
- Local themes inherit from parent themes and can override specific variables

### CSS Variable Naming

- All Bulma CSS variables follow the `--bulma-*` naming convention
- Use the `bulmaVars` prop when you need to set variables not covered by individual props
- Individual props (like `primaryH`) are converted to their corresponding CSS variable names

### Performance Considerations

- Prefer setting themes at higher levels in your component tree rather than deeply nested
- Use `isRoot={true}` sparingly to avoid CSS specificity issues
- CSS variables are inherited, so child themes only need to override specific variables

### Color System

- Bulma uses HSL (Hue, Saturation, Lightness) for its color system
- Hue values range from 0-360 (color wheel degrees)
- Saturation and Lightness are typically percentages (e.g., '50%')
- The scheme variables control the base color relationships

---

## API Reference

### Prop to CSS Variable Conversion

The Theme component automatically converts camelCase prop names to their corresponding CSS custom property names using the following pattern:

```
propName → --bulma-prop-name
```

**Examples:**

- `primaryH` → `--bulma-primary-h`
- `schemeS` → `--bulma-scheme-s`
- `lightL` → `--bulma-light-l`
- `hoverBackgroundLDelta` → `--bulma-hover-background-l-delta`
- `cardContentPadding` → `--bestax-card-content-padding`

### Prop vs bulmaVars

You can use CSS variables in two ways:

1. **Individual Props** (recommended for commonly used variables):

   ```tsx
   <Theme primaryH="270" primaryS="100%" primaryL="50%" />
   ```

2. **bulmaVars Object** (for less common variables or when you have many variables):

   ```tsx
   <Theme
     bulmaVars={{
       '--bulma-primary-h': '270',
       '--bulma-primary-s': '100%',
       '--bulma-primary-l': '50%',
       '--bestax-card-content-padding': '2rem',
     }}
   />
   ```

3. **Combined** (props take precedence over bulmaVars):
   ```tsx
   <Theme
     primaryH="270" // This takes precedence
     bulmaVars={{
       '--bulma-primary-h': '180', // This is overridden
       '--bestax-card-content-padding': '2rem',
     }}
   />
   ```

### All Supported Props

The Theme component supports props for all 500+ Bulma CSS variables. Here's the complete list organized by category:

**Scheme & Base Color Props:**

- `schemeH`, `schemeS`, `lightL`, `lightInvertL`, `darkL`, `darkInvertL`
- `softL`, `boldL`, `softInvertL`, `boldInvertL`
- `hoverBackgroundLDelta`, `activeBackgroundLDelta`, `hoverBorderLDelta`, `activeBorderLDelta`
- `hoverColorLDelta`, `activeColorLDelta`, `hoverShadowADelta`, `activeShadowADelta`

**Color Props:**

- `primaryH`, `primaryS`, `primaryL`, `linkH`, `linkS`, `linkL`
- `infoH`, `infoS`, `infoL`, `successH`, `successS`, `successL`
- `warningH`, `warningS`, `warningL`, `dangerH`, `dangerS`, `dangerL`

**Typography Props:**

- `familyPrimary`, `familySecondary`, `familyCode`
- `sizeSmall`, `sizeNormal`, `sizeMedium`, `sizeLarge`
- `weightLight`, `weightNormal`, `weightMedium`, `weightSemibold`, `weightBold`, `weightExtrabold`
- `bodyBackgroundColor`, `bodySize`, `bodyMinWidth`, `bodyRendering`, `bodyFamily`
- `bodyOverflowX`, `bodyOverflowY`, `bodyColor`, `bodyFontSize`, `bodyWeight`, `bodyLineHeight`
- `codeFamily`, `codePadding`, `codeWeight`, `codeSize`, `smallFontSize`
- `hrBackgroundColor`, `hrHeight`, `hrMargin`, `strongColor`, `strongWeight`
- `preFontSize`, `prePadding`, `preCodeFontSize`

**Layout & Spacing Props:**

- `blockSpacing`, `duration`, `easing`, `speed`, `arrowColor`, `loadingColor`
- `radiusSmall`, `radius`, `radiusMedium`, `radiusLarge`, `radiusRounded`
- `columnGap`, `gridGap`, `gridColumnCount`, `gridColumnMin`
- `gridCellColumnSpan`, `gridCellColumnStart`

**Box Props:**

- `boxBackgroundColor`, `boxColor`, `boxRadius`, `boxShadow`, `boxPadding`
- `boxLinkHoverShadow`, `boxLinkActiveShadow`

**Breadcrumb Props:**

- `breadcrumbItemColor`, `breadcrumbItemHoverColor`, `breadcrumbItemActiveColor`
- `breadcrumbItemPaddingVertical`, `breadcrumbItemPaddingHorizontal`, `breadcrumbItemSeparatorColor`

**Burger Props:**

- `burgerH`, `burgerS`, `burgerL`, `burgerBorderRadius`, `burgerGap`
- `burgerItemHeight`, `burgerItemWidth`

**Card Props:**

- `cardColor`, `cardBackgroundColor`, `cardShadow`, `cardRadius`
- `cardHeaderBackgroundColor`, `cardHeaderColor`, `cardHeaderPadding`
- `cardHeaderShadow`, `cardHeaderWeight`, `cardContentBackgroundColor`
- `cardContentPadding`, `cardFooterBackgroundColor`, `cardFooterBorderTop`
- `cardFooterPadding`, `cardMediaMargin`

**Content Props:**

- `contentHeadingColor`, `contentHeadingWeight`, `contentHeadingLineHeight`
- `contentBlockMarginBottom`, `contentBlockquoteBackgroundColor`, `contentBlockquoteBorderLeft`
- `contentBlockquotePadding`, `contentPrePadding`, `contentTableCellBorder`
- `contentTableCellBorderWidth`, `contentTableCellPadding`, `contentTableCellHeadingColor`
- `contentTableHeadCellBorderWidth`, `contentTableHeadCellColor`
- `contentTableBodyLastRowCellBorderBottomWidth`, `contentTableFootCellBorderWidth`
- `contentTableFootCellColor`

**Control Props:**

- `controlRadius`, `controlRadiusSmall`, `controlBorderWidth`, `controlHeight`
- `controlLineHeight`, `controlPaddingVertical`, `controlPaddingHorizontal`
- `controlSize`, `controlFocusShadowL`

**Delete Props:**

- `deleteDimensions`, `deleteBackgroundL`, `deleteBackgroundAlpha`, `deleteColor`

**Dropdown Props:**

- `dropdownMenuMinWidth`, `dropdownContentBackgroundColor`, `dropdownContentOffset`
- `dropdownContentPaddingBottom`, `dropdownContentPaddingTop`, `dropdownContentRadius`
- `dropdownContentShadow`, `dropdownContentZ`, `dropdownItemH`, `dropdownItemS`
- `dropdownItemL`, `dropdownItemBackgroundL`, `dropdownItemBackgroundLDelta`
- `dropdownItemHoverBackgroundLDelta`, `dropdownItemActiveBackgroundLDelta`
- `dropdownItemColorL`, `dropdownItemSelectedH`, `dropdownItemSelectedS`
- `dropdownItemSelectedL`, `dropdownItemSelectedBackgroundL`, `dropdownItemSelectedColorL`
- `dropdownDividerBackgroundColor`

**File Props:**

- `fileRadius`, `fileNameBorderColor`, `fileNameBorderStyle`, `fileNameBorderWidth`
- `fileNameMaxWidth`, `fileH`, `fileS`, `fileBackgroundL`, `fileBackgroundLDelta`
- `fileHoverBackgroundLDelta`, `fileActiveBackgroundLDelta`, `fileBorderL`
- `fileBorderLDelta`, `fileHoverBorderLDelta`, `fileActiveBorderLDelta`
- `fileCtaColorL`, `fileNameColorL`, `fileColorLDelta`, `fileHoverColorLDelta`
- `fileActiveColorLDelta`

**Footer Props:**

- `footerBackgroundColor`, `footerColor`, `footerPadding`

**Hero Props:**

- `heroBodyPadding`, `heroBodyPaddingTablet`, `heroBodyPaddingSmall`
- `heroBodyPaddingMedium`, `heroBodyPaddingLarge`

**Icon Props:**

- `iconDimensions`, `iconDimensionsSmall`, `iconDimensionsMedium`
- `iconDimensionsLarge`, `iconTextSpacing`

**Input Props:**

- `inputH`, `inputS`, `inputL`, `inputBorderStyle`, `inputBorderL`
- `inputBorderLDelta`, `inputHoverBorderLDelta`, `inputActiveBorderLDelta`
- `inputFocusH`, `inputFocusS`, `inputFocusL`, `inputFocusShadowSize`
- `inputFocusShadowAlpha`, `inputColorL`, `inputBackgroundL`, `inputBackgroundLDelta`
- `inputHeight`, `inputShadow`, `inputPlaceholderColor`, `inputDisabledColor`
- `inputDisabledBackgroundColor`, `inputDisabledBorderColor`, `inputDisabledPlaceholderColor`
- `inputArrow`, `inputIconColor`, `inputIconHoverColor`, `inputIconFocusColor`, `inputRadius`

**Media Props:**

- `mediaBorderColor`, `mediaBorderSize`, `mediaSpacing`, `mediaSpacingLarge`
- `mediaContentSpacing`, `mediaLevel1Spacing`, `mediaLevel1ContentSpacing`, `mediaLevel2Spacing`

**Menu Props:**

- `menuItemH`, `menuItemS`, `menuItemL`, `menuItemBackgroundL`, `menuItemBackgroundLDelta`
- `menuItemHoverBackgroundLDelta`, `menuItemActiveBackgroundLDelta`, `menuItemColorL`
- `menuItemRadius`, `menuItemSelectedH`, `menuItemSelectedS`, `menuItemSelectedL`
- `menuItemSelectedBackgroundL`, `menuItemSelectedColorL`, `menuListBorderLeft`
- `menuListLineHeight`, `menuListLinkPadding`, `menuNestedListMargin`
- `menuNestedListPaddingLeft`, `menuLabelColor`, `menuLabelFontSize`
- `menuLabelLetterSpacing`, `menuLabelSpacing`

**Message Props:**

- `messageH`, `messageS`, `messageBackgroundL`, `messageBorderL`, `messageBorderLDelta`
- `messageBorderStyle`, `messageBorderWidth`, `messageColorL`, `messageRadius`
- `messageHeaderWeight`, `messageHeaderPadding`, `messageHeaderRadius`
- `messageHeaderBodyBorderWidth`, `messageHeaderBackgroundL`, `messageHeaderColorL`
- `messageBodyBorderWidth`, `messageBodyColor`, `messageBodyPadding`
- `messageBodyRadius`, `messageBodyPreCodeBackgroundColor`

**Modal Props:**

- `modalZ`, `modalBackgroundBackgroundColor`, `modalContentWidth`, `modalContentMarginMobile`
- `modalContentSpacingMobile`, `modalContentSpacingTablet`, `modalCloseDimensions`
- `modalCloseRight`, `modalCloseTop`, `modalCardSpacing`, `modalCardHeadBackgroundColor`
- `modalCardHeadPadding`, `modalCardHeadRadius`, `modalCardTitleColor`
- `modalCardTitleLineHeight`, `modalCardTitleSize`, `modalCardFootBackgroundColor`
- `modalCardFootRadius`, `modalCardBodyBackgroundColor`, `modalCardBodyPadding`

**Navbar Props:**

- `navbarH`, `navbarS`, `navbarL`, `navbarBackgroundColor`, `navbarBoxShadowSize`
- `navbarBoxShadowColor`, `navbarPaddingVertical`, `navbarPaddingHorizontal`
- `navbarZ`, `navbarFixedZ`, `navbarItemBackgroundA`, `navbarItemBackgroundL`
- `navbarItemBackgroundLDelta`, `navbarItemHoverBackgroundLDelta`, `navbarItemActiveBackgroundLDelta`
- `navbarItemColorL`, `navbarItemSelectedH`, `navbarItemSelectedS`, `navbarItemSelectedL`
- `navbarItemSelectedBackgroundL`, `navbarItemSelectedColorL`, `navbarItemImgMaxHeight`
- `navbarBurgerColor`, `navbarTabHoverBackgroundColor`, `navbarTabHoverBorderBottomColor`
- `navbarTabActiveColor`, `navbarTabActiveBackgroundColor`, `navbarTabActiveBorderBottomColor`
- `navbarTabActiveBorderBottomStyle`, `navbarTabActiveBorderBottomWidth`
- `navbarDropdownBackgroundColor`, `navbarDropdownBorderL`, `navbarDropdownBorderColor`
- `navbarDropdownBorderStyle`, `navbarDropdownBorderWidth`, `navbarDropdownOffset`
- `navbarDropdownArrow`, `navbarDropdownRadius`, `navbarDropdownZ`
- `navbarDropdownBoxedRadius`, `navbarDropdownBoxedShadow`, `navbarDropdownItemH`
- `navbarDropdownItemS`, `navbarDropdownItemL`, `navbarDropdownItemBackgroundL`
- `navbarDropdownItemColorL`, `navbarDividerBackgroundL`, `navbarDividerHeight`
- `navbarBottomBoxShadowSize`

**Notification Props:**

- `notificationH`, `notificationS`, `notificationBackgroundL`, `notificationColorL`
- `notificationCodeBackgroundColor`, `notificationRadius`, `notificationPadding`

**Pagination Props:**

- `paginationMargin`, `paginationMinWidth`, `paginationItemH`, `paginationItemS`
- `paginationItemL`, `paginationItemBackgroundLDelta`, `paginationItemHoverBackgroundLDelta`
- `paginationItemActiveBackgroundLDelta`, `paginationItemBorderStyle`, `paginationItemBorderWidth`
- `paginationItemBorderL`, `paginationItemBorderLDelta`, `paginationItemHoverBorderLDelta`
- `paginationItemActiveBorderLDelta`, `paginationItemFocusBorderLDelta`, `paginationItemColorL`
- `paginationItemFontSize`, `paginationItemMargin`, `paginationItemPaddingLeft`
- `paginationItemPaddingRight`, `paginationItemOuterShadowH`, `paginationItemOuterShadowS`
- `paginationItemOuterShadowL`, `paginationItemOuterShadowA`, `paginationNavPaddingLeft`
- `paginationNavPaddingRight`, `paginationDisabledColor`, `paginationDisabledBackgroundColor`
- `paginationDisabledBorderColor`, `paginationCurrentColor`, `paginationCurrentBackgroundColor`
- `paginationCurrentBorderColor`, `paginationEllipsisColor`, `paginationShadowInset`
- `paginationSelectedItemH`, `paginationSelectedItemS`, `paginationSelectedItemL`
- `paginationSelectedItemBackgroundL`, `paginationSelectedItemBorderL`, `paginationSelectedItemColorL`

**Panel Props:**

- `panelMargin`, `panelItemBorder`, `panelRadius`, `panelShadow`, `panelHeadingLineHeight`
- `panelHeadingPadding`, `panelHeadingRadius`, `panelHeadingSize`, `panelHeadingWeight`
- `panelTabsFontSize`, `panelTabBorderBottomColor`, `panelTabBorderBottomStyle`
- `panelTabBorderBottomWidth`, `panelTabActiveColor`, `panelListItemColor`
- `panelListItemHoverColor`, `panelBlockColor`, `panelBlockHoverBackgroundColor`
- `panelBlockActiveBorderLeftColor`, `panelBlockActiveColor`, `panelBlockActiveIconColor`
- `panelIconColor`

**Progress Props:**

- `progressBorderRadius`, `progressBarBackgroundColor`, `progressValueBackgroundColor`
- `progressIndeterminateDuration`

**Section Props:**

- `sectionPadding`, `sectionPaddingDesktop`, `sectionPaddingMedium`, `sectionPaddingLarge`

**Skeleton Props:**

- `skeletonBackground`, `skeletonRadius`, `skeletonBlockMinHeight`, `skeletonLinesGap`
- `skeletonLineHeight`

**Table Props:**

- `tableColor`, `tableBackgroundColor`, `tableCellBorderColor`, `tableCellBorderStyle`
- `tableCellBorderWidth`, `tableCellPadding`, `tableCellHeadingColor`, `tableCellTextAlign`
- `tableHeadCellBorderWidth`, `tableHeadCellColor`, `tableFootCellBorderWidth`
- `tableFootCellColor`, `tableHeadBackgroundColor`, `tableBodyBackgroundColor`
- `tableFootBackgroundColor`, `tableRowHoverBackgroundColor`, `tableRowActiveBackgroundColor`
- `tableRowActiveColor`, `tableStripedRowEvenBackgroundColor`, `tableStripedRowEvenHoverBackgroundColor`

**Tabs Props:**

- `tabsBorderBottomColor`, `tabsBorderBottomStyle`, `tabsBorderBottomWidth`
- `tabsLinkColor`, `tabsLinkHoverBorderBottomColor`, `tabsLinkHoverColor`
- `tabsLinkActiveBorderBottomColor`, `tabsLinkActiveColor`, `tabsLinkPadding`
- `tabsBoxedLinkRadius`, `tabsBoxedLinkHoverBackgroundColor`, `tabsBoxedLinkHoverBorderBottomColor`
- `tabsBoxedLinkActiveBackgroundColor`, `tabsBoxedLinkActiveBorderColor`
- `tabsBoxedLinkActiveBorderBottomColor`, `tabsToggleLinkBorderColor`, `tabsToggleLinkBorderStyle`
- `tabsToggleLinkBorderWidth`, `tabsToggleLinkHoverBackgroundColor`, `tabsToggleLinkHoverBorderColor`
- `tabsToggleLinkRadius`, `tabsToggleLinkActiveBackgroundColor`, `tabsToggleLinkActiveBorderColor`
- `tabsToggleLinkActiveColor`

**Tag Props:**

- `tagH`, `tagS`, `tagBackgroundL`, `tagBackgroundLDelta`, `tagHoverBackgroundLDelta`
- `tagActiveBackgroundLDelta`, `tagColorL`, `tagRadius`, `tagDeleteMargin`

**Title & Subtitle Props:**

- `titleColor`, `titleFamily`, `titleSize`, `titleWeight`, `titleLineHeight`
- `titleStrongColor`, `titleStrongWeight`, `titleSubSize`, `titleSupSize`
- `subtitleColor`, `subtitleFamily`, `subtitleSize`, `subtitleWeight`
- `subtitleLineHeight`, `subtitleStrongColor`, `subtitleStrongWeight`

### TypeScript Support

All props are fully typed in TypeScript. Use IDE autocomplete to discover available props:

```tsx
// TypeScript will provide autocomplete for all available props
<Theme
  primaryH="270"
  cardContent={/* TypeScript autocomplete will show all card-related props */}
/>
```

---

## See Also

- [ConfigProvider](./config.md) - For class prefixing and configuration
- [useBulmaClasses](./usebulmaclasses.md) - For applying Bulma helper classes
- [Bulma CSS Variables Documentation](https://bulma.io/documentation/features/css-variables/) - Official Bulma CSS variables reference

---

## useBulmaClasses


## Overview

`useBulmaClasses` is a custom React hook that generates Bulma helper class strings from a set of props. It makes it easy to apply color, spacing, alignment, typography, flexbox, and other Bulma utility classes to your components in a type-safe, composable way. It also separates out any non-helper props for direct use on elements.

---

## Import

```tsx

```

---

## API

```tsx
const { bulmaHelperClasses, rest } = useBulmaClasses(props);
```

- **props**: An object supporting all Bulma helper class props (see table below), plus any additional props.
- **bulmaHelperClasses**: A string of Bulma utility classes to be applied to your element.
- **rest**: An object of all remaining props (with helper props stripped out), suitable for spreading onto your component.

---

## Composable Mini-Hooks

`useBulmaClasses` remains the everything-hook — it is what every bestax-bulma component uses internally, and it covers the full helper prop surface with zero behavior change. If you are building a custom component that only needs a slice of that surface, you can reach for one of six composable mini hooks instead. Each mini hook accepts just its own group of props and returns a plain class string, which you can combine with the [`classNames`](./classnames.md) utility.

| Hook                   | Props Covered                                                                                                                                  | Returns                                                                                                                                                                                 |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `useColorClasses`      | `color`, `colorShade`, `backgroundColor`, `backgroundColorShade`                                                                               | Text and background color classes, including palette shades                                                                                                                             |
| `useSpacingClasses`    | `m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my`, `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py`                                                               | Margin and padding classes                                                                                                                                                              |
| `useTypographyClasses` | `textSize`, `textAlign`, `textTransform`, `textWeight`, `fontFamily`, `viewport`, plus `textSize{Mobile..Fullhd}`, `textAlign{Mobile..Fullhd}` | Typography classes, including responsive size/alignment variants                                                                                                                        |
| `useVisibilityClasses` | `display`, `visibility`, `viewport`, plus `display{Mobile..Fullhd}`, `visibility{Mobile..Fullhd}`                                              | Display and visibility classes (this hook owns all display emission)                                                                                                                    |
| `useFlexboxClasses`    | `flexDirection`, `flexWrap`, `justifyContent`, `alignContent`, `alignItems`, `alignSelf`, `flexGrow`, `flexShrink`                             | Flexbox classes; container classes are only emitted when a `display`/`display{Viewport}` prop is `flex`/`inline-flex`, item classes (`alignSelf`, `flexGrow`, `flexShrink`) always emit |
| `useOtherClasses`      | `float`, `overflow`, `overlay`, `interaction`, `cursor`, `radius`, `shadow`, `responsive`, `skeleton`, `clearfix`, `relative`, `fullHeight`    | Miscellaneous utility classes                                                                                                                                                           |

All six hooks (and `classNames`) are exported from the package root:

```tsx

  useColorClasses,
  useSpacingClasses,
  classNames,
} from '@allxsmith/bestax-bulma';
```

Here is a small custom component that only needs color and spacing helpers:

```tsx live
function example() {
  function PriceTag({
    color,
    backgroundColor,
    backgroundColorShade,
    m,
    children,
  }) {
    const colorClasses = useColorClasses({
      color,
      backgroundColor,
      backgroundColorShade,
    });
    const spacingClasses = useSpacingClasses({ m });
    return (
      
        {children}
      
    );
  }

  return (
    
      <PriceTag color="white" backgroundColor="success" m="2">
        $19.99
      </PriceTag>
      <PriceTag
        color="white"
        backgroundColor="danger"
        backgroundColorShade="dark"
        m="2"
      >
        $49.99
      </PriceTag>
    
  );
}
```

:::note useFlexboxClasses and display

`useFlexboxClasses` only emits container classes (`flexDirection`, `flexWrap`, `justifyContent`, `alignContent`, `alignItems`) when a `display` or `display{Viewport}` prop is `flex` or `inline-flex` — it reads those display props for gating but never emits the display class itself. Pair it with `useVisibilityClasses` (which owns display emission), or just use `useBulmaClasses`.

:::

---

## Supported Props

Below is the full list of supported props, derived from the `BulmaClassesProps` TypeScript definition:

| Prop                   | Type / Example Value                                                                                                                                                                                                                                 | Effect / Example Class                                       |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| `color`                | `'primary'`, `'link'`, `'info'`, `'success'`, `'warning'`, `'danger'`, `'black'`, `'black-bis'`, `'black-ter'`, `'grey-darker'`, `'grey-dark'`, `'grey'`, `'grey-light'`, `'grey-lighter'`, `'white'`, `'light'`, `'dark'`, `'inherit'`, `'current'` | `has-text-primary`, `has-text-grey-dark`, `has-text-inherit` |
| `backgroundColor`      | Same as `color`                                                                                                                                                                                                                                      | `has-background-warning`                                     |
| `colorShade`           | `'00'`, `'05'`, `'10'`, `'15'`, `'20'`, `'25'`, `'30'`, `'35'`, `'40'`, `'45'`, `'50'`, `'55'`, `'60'`, `'65'`, `'70'`, `'75'`, `'80'`, `'85'`, `'90'`, `'95'`, `'invert'`, `'light'`, `'dark'`, `'soft'`, `'bold'`, `'on-scheme'`                   | `has-text-primary-25`                                        |
| `backgroundColorShade` | `'00'`, `'05'`, `'10'`, `'15'`, `'20'`, `'25'`, `'30'`, `'35'`, `'40'`, `'45'`, `'50'`, `'55'`, `'60'`, `'65'`, `'70'`, `'75'`, `'80'`, `'85'`, `'90'`, `'95'`, `'invert'`, `'light'`, `'dark'`, `'soft'`, `'bold'`, `'on-scheme'`                   | `has-background-info-dark`                                   |
| `m`                    | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `m-4`, `m-auto`                                              |
| `mt`                   | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `mt-2`                                                       |
| `mr`                   | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `mr-6`                                                       |
| `mb`                   | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `mb-0`                                                       |
| `ml`                   | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `ml-auto`                                                    |
| `mx`                   | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `mx-2`                                                       |
| `my`                   | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `my-5`                                                       |
| `p`                    | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `p-3`, `p-auto`                                              |
| `pt`                   | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `pt-1`                                                       |
| `pr`                   | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `pr-6`                                                       |
| `pb`                   | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `pb-0`                                                       |
| `pl`                   | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `pl-4`                                                       |
| `px`                   | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `px-1`                                                       |
| `py`                   | `'0'..'6'`, `'auto'`                                                                                                                                                                                                                                 | `py-6`                                                       |
| `textSize`             | `'1'..'7'`                                                                                                                                                                                                                                           | `is-size-3`                                                  |
| `textAlign`            | `'centered'`, `'justified'`, `'left'`, `'right'`                                                                                                                                                                                                     | `has-text-centered`                                          |
| `textTransform`        | `'capitalized'`, `'lowercase'`, `'uppercase'`, `'italic'`                                                                                                                                                                                            | `is-uppercase`, `is-italic`                                  |
| `textWeight`           | `'light'`, `'normal'`, `'medium'`, `'semibold'`, `'bold'`                                                                                                                                                                                            | `has-text-weight-bold`                                       |
| `fontFamily`           | `'sans-serif'`, `'monospace'`, `'primary'`, `'secondary'`, `'code'`                                                                                                                                                                                  | `is-family-monospace`                                        |
| `display`              | `'block'`, `'flex'`, `'inline'`, `'inline-block'`, `'inline-flex'`, `'none'`                                                                                                                                                                         | `is-flex`, `is-inline-block`, `is-hidden`                    |
| `visibility`           | `'hidden'`, `'sr-only'`, `'invisible'`                                                                                                                                                                                                               | `is-hidden`, `is-sr-only`, `is-invisible`                    |
| `flexDirection`        | `'row'`, `'row-reverse'`, `'column'`, `'column-reverse'`                                                                                                                                                                                             | `is-flex-direction-row`                                      |
| `flexWrap`             | `'nowrap'`, `'wrap'`, `'wrap-reverse'`                                                                                                                                                                                                               | `is-flex-wrap-nowrap`                                        |
| `justifyContent`       | `'flex-start'`, `'flex-end'`, `'center'`, `'space-between'`, `'space-around'`, `'space-evenly'`, `'start'`, `'end'`, `'left'`, `'right'`                                                                                                             | `is-justify-content-center`                                  |
| `alignContent`         | `'flex-start'`, `'flex-end'`, `'center'`, `'space-between'`, `'space-around'`, `'space-evenly'`, `'stretch'`                                                                                                                                         | `is-align-content-stretch`                                   |
| `alignItems`           | `'stretch'`, `'flex-start'`, `'flex-end'`, `'center'`, `'baseline'`, `'start'`, `'end'`                                                                                                                                                              | `is-align-items-center`                                      |
| `alignSelf`            | `'auto'`, `'flex-start'`, `'flex-end'`, `'center'`, `'baseline'`, `'stretch'`                                                                                                                                                                        | `is-align-self-center`                                       |
| `flexGrow`             | `'0'`, `'1'`, `'2'`, `'3'`, `'4'`, `'5'`                                                                                                                                                                                                             | `is-flex-grow-1`                                             |
| `flexShrink`           | `'0'`, `'1'`, `'2'`, `'3'`, `'4'`, `'5'`                                                                                                                                                                                                             | `is-flex-shrink-0`                                           |
| `float`                | `'left'`, `'right'`                                                                                                                                                                                                                                  | `is-pulled-left`, `is-pulled-right`                          |
| `overflow`             | `'clipped'`                                                                                                                                                                                                                                          | `is-clipped`                                                 |
| `overlay`              | `true`                                                                                                                                                                                                                                               | `is-overlay`                                                 |
| `interaction`          | `'unselectable'`, `'clickable'`                                                                                                                                                                                                                      | `is-unselectable`                                            |
| `cursor`               | `'pointer'`, `'help'`                                                                                                                                                                                                                                | `is-clickable`, `is-cursor-help`                             |
| `radius`               | `'radiusless'`                                                                                                                                                                                                                                       | `is-radiusless`                                              |
| `shadow`               | `'shadowless'`                                                                                                                                                                                                                                       | `is-shadowless`                                              |
| `responsive`           | `'mobile'`, `'narrow'`                                                                                                                                                                                                                               | `is-mobile`, `is-narrow`                                     |
| `viewport`             | `'mobile'`, `'tablet'`, `'desktop'`, `'widescreen'`, `'fullhd'`                                                                                                                                                                                      | Adds viewport suffix to supported properties                 |
| `skeleton`             | `true`                                                                                                                                                                                                                                               | `is-skeleton`                                                |
| `clearfix`             | `true`                                                                                                                                                                                                                                               | `is-clearfix`                                                |
| `relative`             | `true`                                                                                                                                                                                                                                               | `is-relative`                                                |
| `fullHeight`           | `true`                                                                                                                                                                                                                                               | `is-full-height`                                             |

### Viewport-Specific Properties

The following properties allow you to set different values for each viewport breakpoint:

| Prop                   | Type / Example Value                                            | Effect / Example Class                                                     |
| ---------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `displayMobile`        | `'block'`, `'flex'`, `'inline'`, `'none'`, etc.                 | `is-block-mobile`, `is-flex-mobile`, `is-hidden-mobile`                    |
| `displayTablet`        | Same as above                                                   | `is-block-tablet`, `is-flex-tablet`, `is-hidden-tablet`                    |
| `displayDesktop`       | Same as above                                                   | `is-block-desktop`, `is-flex-desktop`, `is-hidden-desktop`                 |
| `displayWidescreen`    | Same as above                                                   | `is-block-widescreen`, `is-flex-widescreen`                                |
| `displayFullhd`        | Same as above                                                   | `is-block-fullhd`, `is-flex-fullhd`                                        |
| `textSizeMobile`       | `'1'..'7'`                                                      | `is-size-3-mobile`, `is-size-5-mobile`                                     |
| `textSizeTablet`       | `'1'..'7'`                                                      | `is-size-3-tablet`, `is-size-5-tablet`                                     |
| `textSizeDesktop`      | `'1'..'7'`                                                      | `is-size-3-desktop`, `is-size-5-desktop`                                   |
| `textSizeWidescreen`   | `'1'..'7'`                                                      | `is-size-3-widescreen`, `is-size-5-widescreen`                             |
| `textSizeFullhd`       | `'1'..'7'`                                                      | `is-size-3-fullhd`, `is-size-5-fullhd`                                     |
| `textAlignMobile`      | `'centered'`, `'left'`, `'right'`, `'justified'`                | `has-text-centered-mobile`, `has-text-left-mobile`                         |
| `textAlignTablet`      | Same as above                                                   | `has-text-centered-tablet`, `has-text-left-tablet`                         |
| `textAlignDesktop`     | Same as above                                                   | `has-text-centered-desktop`, `has-text-left-desktop`                       |
| `textAlignWidescreen`  | Same as above                                                   | `has-text-centered-widescreen`, `has-text-left-widescreen`                 |
| `textAlignFullhd`      | Same as above                                                   | `has-text-centered-fullhd`, `has-text-left-fullhd`                         |
| `visibilityMobile`     | `'hidden'`, `'sr-only'`, `'invisible'`                          | `is-hidden-mobile`, `is-sr-only-mobile`, `is-invisible-mobile`             |
| `visibilityTablet`     | Same as above                                                   | `is-hidden-tablet`, `is-sr-only-tablet`, `is-invisible-tablet`             |
| `visibilityDesktop`    | Same as above                                                   | `is-hidden-desktop`, `is-sr-only-desktop`, `is-invisible-desktop`          |
| `visibilityWidescreen` | Same as above                                                   | `is-hidden-widescreen`, `is-sr-only-widescreen`, `is-invisible-widescreen` |
| `visibilityFullhd`     | Same as above                                                   | `is-hidden-fullhd`, `is-sr-only-fullhd`, `is-invisible-fullhd`             |
| `responsive`           | `'mobile'`, `'narrow'`                                          | `is-mobile`, `is-narrow`                                                   |
| `clearfix`             | `true`                                                          | `is-clearfix`                                                              |
| `relative`             | `true`                                                          | `is-relative`                                                              |
| `viewport`             | `'mobile'`, `'tablet'`, `'desktop'`, `'widescreen'`, `'fullhd'` | Adds suffix, e.g. `-mobile`, `-desktop`                                    |

---

### Full TypeScript Definition

`BulmaClassesProps` is composed from the six group interfaces, each of which is also exported (along with the shared `BulmaViewportProps` and `BulmaDisplayProps` types) and accepted by the corresponding [mini hook](#composable-mini-hooks):

```ts
export interface BulmaClassesProps
  extends
    BulmaColorProps,
    BulmaSpacingProps,
    BulmaTypographyProps,
    BulmaVisibilityProps,
    BulmaFlexboxProps,
    BulmaOtherProps {}

export type BulmaViewportProps =
  'mobile' | 'tablet' | 'desktop' | 'widescreen' | 'fullhd';

export type BulmaDisplayProps =
  'block' | 'flex' | 'inline' | 'inline-block' | 'inline-flex' | 'none';

export interface BulmaColorProps {
  color?:
    | 'primary'
    | 'link'
    | 'info'
    | 'success'
    | 'warning'
    | 'danger'
    | 'black'
    | 'black-bis'
    | 'black-ter'
    | 'grey-darker'
    | 'grey-dark'
    | 'grey'
    | 'grey-light'
    | 'grey-lighter'
    | 'white'
    | 'light'
    | 'dark'
    | 'inherit'
    | 'current';
  colorShade?:
    | '00'
    | '05'
    | '10'
    | '15'
    | '20'
    | '25'
    | '30'
    | '35'
    | '40'
    | '45'
    | '50'
    | '55'
    | '60'
    | '65'
    | '70'
    | '75'
    | '80'
    | '85'
    | '90'
    | '95'
    | 'invert'
    | 'light'
    | 'dark'
    | 'soft'
    | 'bold'
    | 'on-scheme';
  backgroundColor?: BulmaColorProps['color'];
  backgroundColorShade?: BulmaColorProps['colorShade'];
}

export interface BulmaSpacingProps {
  m?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
  mt?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
  mr?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
  mb?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
  ml?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
  mx?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
  my?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
  p?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
  pt?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
  pr?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
  pb?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
  pl?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
  px?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
  py?: '0' | '1' | '2' | '3' | '4' | '5' | '6' | 'auto';
}

export interface BulmaTypographyProps {
  textSize?: '1' | '2' | '3' | '4' | '5' | '6' | '7';
  textAlign?: 'centered' | 'justified' | 'left' | 'right';
  textTransform?: 'capitalized' | 'lowercase' | 'uppercase' | 'italic';
  textWeight?: 'light' | 'normal' | 'medium' | 'semibold' | 'bold';
  fontFamily?: 'sans-serif' | 'monospace' | 'primary' | 'secondary' | 'code';
  viewport?: BulmaViewportProps;
  textSizeMobile?: '1' | '2' | '3' | '4' | '5' | '6' | '7';
  textSizeTablet?: '1' | '2' | '3' | '4' | '5' | '6' | '7';
  textSizeDesktop?: '1' | '2' | '3' | '4' | '5' | '6' | '7';
  textSizeWidescreen?: '1' | '2' | '3' | '4' | '5' | '6' | '7';
  textSizeFullhd?: '1' | '2' | '3' | '4' | '5' | '6' | '7';
  textAlignMobile?: 'centered' | 'justified' | 'left' | 'right';
  textAlignTablet?: 'centered' | 'justified' | 'left' | 'right';
  textAlignDesktop?: 'centered' | 'justified' | 'left' | 'right';
  textAlignWidescreen?: 'centered' | 'justified' | 'left' | 'right';
  textAlignFullhd?: 'centered' | 'justified' | 'left' | 'right';
}

export interface BulmaVisibilityProps {
  display?: BulmaDisplayProps;
  visibility?: 'hidden' | 'sr-only' | 'invisible';
  viewport?: BulmaViewportProps;
  displayMobile?: BulmaDisplayProps;
  displayTablet?: BulmaDisplayProps;
  displayDesktop?: BulmaDisplayProps;
  displayWidescreen?: BulmaDisplayProps;
  displayFullhd?: BulmaDisplayProps;
  visibilityMobile?: 'hidden' | 'sr-only' | 'invisible';
  visibilityTablet?: 'hidden' | 'sr-only' | 'invisible';
  visibilityDesktop?: 'hidden' | 'sr-only' | 'invisible';
  visibilityWidescreen?: 'hidden' | 'sr-only' | 'invisible';
  visibilityFullhd?: 'hidden' | 'sr-only' | 'invisible';
}

export interface BulmaFlexboxProps {
  flexDirection?: 'row' | 'row-reverse' | 'column' | 'column-reverse';
  flexWrap?: 'nowrap' | 'wrap' | 'wrap-reverse';
  justifyContent?:
    | 'flex-start'
    | 'flex-end'
    | 'center'
    | 'space-between'
    | 'space-around'
    | 'space-evenly'
    | 'start'
    | 'end'
    | 'left'
    | 'right';
  alignContent?:
    | 'flex-start'
    | 'flex-end'
    | 'center'
    | 'space-between'
    | 'space-around'
    | 'space-evenly'
    | 'stretch';
  alignItems?:
    | 'stretch'
    | 'flex-start'
    | 'flex-end'
    | 'center'
    | 'baseline'
    | 'start'
    | 'end';
  alignSelf?:
    'auto' | 'flex-start' | 'flex-end' | 'center' | 'baseline' | 'stretch';
  flexGrow?: '0' | '1' | '2' | '3' | '4' | '5';
  flexShrink?: '0' | '1' | '2' | '3' | '4' | '5';
}

export interface BulmaOtherProps {
  float?: 'left' | 'right';
  overflow?: 'clipped';
  overlay?: boolean;
  interaction?: 'unselectable' | 'clickable';
  cursor?: 'pointer' | 'help';
  radius?: 'radiusless';
  shadow?: 'shadowless';
  responsive?: 'mobile' | 'narrow';
  skeleton?: boolean;
  clearfix?: boolean;
  relative?: boolean;
  fullHeight?: boolean;
}
```

---

## Usage

:::info Container components pad themselves
Container components like `Box`, `Notification`, `Message`, and `Card` ship with Bulma's standard, pleasant padding and stack with sensible default spacing. The examples below only add margin or padding props when spacing itself is what's being demonstrated.
:::

### Basic Example

```tsx live
function example() {
  const { bulmaHelperClasses, rest } = useBulmaClasses({
    color: 'link',
    backgroundColor: 'primary',
    p: '4',
    textAlign: 'centered',
    id: 'card1',
  });

  return JSON.stringify({ bulmaHelperClasses, rest });
  // bulmaHelperClasses: 'has-text-link has-background-primary p-4 has-text-centered'
  // rest: { className: 'custom-card', id: 'card1' }
}
```

Apply to your component:

```tsx live
function example() {
  const { bulmaHelperClasses, rest } = useBulmaClasses({
    color: 'link',
    backgroundColor: 'primary',
    p: '4',
    textAlign: 'centered',
    id: 'card1',
  });

  return (
    
      Card content
    
  );
}
```

---

### Responsive Props

```tsx live
function example() {
  const { bulmaHelperClasses } = useBulmaClasses({
    color: 'link',
    backgroundColor: 'primary',
    m: '2',
    textAlign: 'centered',
    viewport: 'mobile',
  });
  return JSON.stringify({ bulmaHelperClasses });
  // bulmaHelperClasses: 'has-text-info-mobile m-2-mobile has-text-centered-mobile'
}
```

---

### With Flexbox Helpers

Flexbox properties are divided into two categories:

#### Container Properties

These properties apply to elements with `display: flex` or `display: inline-flex`:

- `flexDirection` - Direction of flex items
- `flexWrap` - Whether items wrap
- `justifyContent` - Alignment along main axis
- `alignContent` - Alignment of wrapped lines
- `alignItems` - Alignment along cross axis

#### Item Properties

These properties apply to flex items (children of flex containers) and **do not require** the element itself to have `display: flex`:

- `alignSelf` - Override container's alignItems for this item
- `flexGrow` - How much the item should grow
- `flexShrink` - How much the item should shrink

```tsx live
function example() {
  const { bulmaHelperClasses } = useBulmaClasses({
    display: 'flex',
    flexDirection: 'column',
    alignItems: 'center',
    justifyContent: 'center',
    gap: '4',
  });
  return JSON.stringify({ bulmaHelperClasses });
  // bulmaHelperClasses: 'is-flex is-flex-direction-column is-align-items-center is-justify-content-center'
}
```

Example with flex items:

```tsx
// Container with display flex
<Box display="flex" alignItems="center">
  {/* Items don't need display flex to use alignSelf, flexGrow, flexShrink */}
  <Button alignSelf="flex-start">Start</Button>
  <Button alignSelf="center" flexGrow="1">
    Center & Grow
  </Button>
  <Button alignSelf="flex-end" flexShrink="0">
    End & No Shrink
  </Button>
</Box>
```

---

### Using with Components

:::note These are illustrations, not replacements
The snippets below rebuild simplified components by hand purely to show how `useBulmaClasses` fits inside one. In a real app, use the library's own [Columns / Column](../columns/columns.md) and [Card](../components/card.md) components — they already wire up `useBulmaClasses` (plus prefixes, modifiers, and more) for you.
:::

#### Columns

`MyColumns` forwards all of its props to `useBulmaClasses` — the `textAlign` and `textTransform` helper props below flow through `props` into the hook (producing `has-text-centered is-uppercase`), while anything the hook doesn't recognize comes back in `rest` and lands on the ``:

```tsx live
function example() {
  function MyColumns({ children, ...props }) {
    const { bulmaHelperClasses, rest } = useBulmaClasses(props);
    return (
      
        {children}
      
    );
  }

  return (
    <MyColumns textAlign="centered" textTransform="uppercase">
      
        <Notification color="primary">Left</Notification>
      
      
        <Notification color="info">Right</Notification>
      
    </MyColumns>
  );
}
```

#### Card

```tsx live
function example() {
  const props = {};

  const textColor = 'white';
  const bgColor = 'primary';
  const hasShadow = true;
  const className = 'custom-card';
  const children = Making a custom card;
  const p = '4';

  const { bulmaHelperClasses, rest } = useBulmaClasses({
    color: textColor,
    backgroundColor: bgColor,
    p,
    ...props,
  });
  const cardClasses = classNames('card', className, bulmaHelperClasses, {
    'is-shadowless': !hasShadow,
  });
  return (
    
      {children}
    
  );
}
```

---

### Colors

Use the `color` prop to apply Bulma color classes. Here, each button demonstrates a different color:

```tsx live
<Buttons>
  <Button color="primary">Primary</Button>
  <Button color="link">Link</Button>
  <Button color="info">Info</Button>
  <Button color="success">Success</Button>
  <Button color="warning">Warning</Button>
  <Button color="danger">Danger</Button>
  <Button color="black">Black</Button>
  <Button color="white">White</Button>
</Buttons>
```

### Background Color

Use the `backgroundColor` prop to set the background color. Pair it with a text color that keeps the label readable on each background:

```tsx live
<Columns isMultiline>
  <Column size="one-quarter">
    <Box backgroundColor="primary" textColor="white">
      Primary
    </Box>
  </Column>
  <Column size="one-quarter">
    <Box backgroundColor="link" textColor="white">
      Link
    </Box>
  </Column>
  <Column size="one-quarter">
    <Box backgroundColor="info" textColor="white">
      Info
    </Box>
  </Column>
  <Column size="one-quarter">
    <Box backgroundColor="success" textColor="white">
      Success
    </Box>
  </Column>
  <Column size="one-quarter">
    <Box backgroundColor="warning" textColor="black">
      Warning
    </Box>
  </Column>
  <Column size="one-quarter">
    <Box backgroundColor="danger" textColor="white">
      Danger
    </Box>
  </Column>
  <Column size="one-quarter">
    <Box backgroundColor="black" textColor="white">
      Black
    </Box>
  </Column>
  <Column size="one-quarter">
    <Box backgroundColor="white" textColor="black">
      White
    </Box>
  </Column>
</Columns>
```

### Color Shade

`colorShade` refines the **text color** — it pairs with the hook's `color` prop (exposed as `textColor` on components, where `color` is the component's own modifier). Here, each line steps through the primary palette:

```tsx live
<>
  <Paragraph textColor="primary" colorShade="10" textWeight="semibold">
    Primary 10
  </Paragraph>
  <Paragraph textColor="primary" colorShade="30" textWeight="semibold">
    Primary 30
  </Paragraph>
  <Paragraph textColor="primary" colorShade="60" textWeight="semibold">
    Primary 60
  </Paragraph>
  <Paragraph textColor="primary" colorShade="90" textWeight="semibold">
    Primary 90
  </Paragraph>
  <Paragraph textColor="primary" colorShade="invert" textWeight="semibold">
    Primary Invert
  </Paragraph>
</>
```

### Background Color Shade

Background shades use their own prop: `backgroundColorShade` pairs with `backgroundColor`, independently of `colorShade` (which pairs with the text color). Low shade numbers are dark and high numbers are light, so dark shades get light text and light shades get dark text to keep each label readable:

```tsx live
<Columns isMultiline>
  <Column size="one-quarter">
    <Box backgroundColor="primary" backgroundColorShade="10" textColor="white">
      Primary 10
    </Box>
  </Column>
  <Column size="one-quarter">
    <Box backgroundColor="primary" backgroundColorShade="30" textColor="white">
      Primary 30
    </Box>
  </Column>
  <Column size="one-quarter">
    <Box backgroundColor="primary" backgroundColorShade="60" textColor="black">
      Primary 60
    </Box>
  </Column>
  <Column size="one-quarter">
    <Box backgroundColor="primary" backgroundColorShade="90" textColor="black">
      Primary 90
    </Box>
  </Column>
  <Column size="one-quarter">
    <Box
      backgroundColor="primary"
      backgroundColorShade="invert"
      textColor="white"
    >
      Primary Invert
    </Box>
  </Column>
</Columns>
```

Because the two shade props are independent, you can shade the text and the background at the same time — a dark background shade with a light text shade of the same color reads well in both themes:

```tsx live
<Box
  backgroundColor="primary"
  backgroundColorShade="15"
  textColor="primary"
  colorShade="85"
>
  Primary text shade 85 on a primary background shade 15
</Box>
```

### Margin

Use margin props to add spacing. Here, margin is applied to buttons, and to a row of buttons using the `Buttons` component:

```tsx live
<>
  <Buttons>
    <Button>Left</Button>
    <Button m="4">Margin 4</Button>
    <Button>Right</Button>
  </Buttons>
  <Buttons mt="5" mb="5">
    <Button>Top/Bottom Margin</Button>
    <Button>Row 2</Button>
  </Buttons>
</>
```

### Text Size

Apply `textSize` to Notifications to illustrate different sizes:

```tsx live
<>
  <Notification textSize="1">Size 1</Notification>
  <Notification textSize="3">Size 3</Notification>
  <Notification textSize="5">Size 5</Notification>
  <Notification textSize="7">Size 7</Notification>
</>
```

### Text Align

Apply `textAlign` to a Box to illustrate text alignment:

```tsx live
<>
  <Box textAlign="centered">Centered text</Box>
  <Box textAlign="right">Right aligned text</Box>
  <Box textAlign="left">Left aligned text</Box>
</>
```

### Text Transform

Apply `textTransform` to a Content tag with a paragraph of the Declaration of Independence:

```tsx live
<>
  <Box>
    <Content textTransform="uppercase">
      
        We hold these truths to be self-evident, that all men are created
        equal...
      
    </Content>
  </Box>
  <Box>
    <Content textTransform="lowercase">
      
        We hold these truths to be self-evident, that all men are created
        equal...
      
    </Content>
  </Box>
  <Box>
    <Content textTransform="capitalized">
      
        We hold these truths to be self-evident, that all men are created
        equal...
      
    </Content>
  </Box>
  <Box>
    <Content textTransform="italic">
      
        We hold these truths to be self-evident, that all men are created
        equal...
      
    </Content>
  </Box>
</>
```

### Text Weight

Apply `textWeight` to Content tags to illustrate different font weights:

```tsx live
<>
  <Box>
    <Content textWeight="light">
      
        We hold these truths to be self-evident, that all men are created
        equal...
      
    </Content>
  </Box>
  <Box>
    <Content textWeight="normal">
      
        We hold these truths to be self-evident, that all men are created
        equal...
      
    </Content>
  </Box>
  <Box>
    <Content textWeight="medium">
      
        We hold these truths to be self-evident, that all men are created
        equal...
      
    </Content>
  </Box>
  <Box>
    <Content textWeight="bold">
      
        We hold these truths to be self-evident, that all men are created
        equal...
      
    </Content>
  </Box>
</>
```

### Font Family

Use Content blocks with different font families:

```tsx live
<>
  <Box>
    <Content fontFamily="sans-serif">
      
        We hold these truths to be self-evident, that all men are created
        equal...
      
    </Content>
  </Box>
  <Box>
    <Content fontFamily="monospace">
      
        We hold these truths to be self-evident, that all men are created
        equal...
      
    </Content>
  </Box>
  <Box>
    <Content fontFamily="primary">
      
        We hold these truths to be self-evident, that all men are created
        equal...
      
    </Content>
  </Box>
  <Box>
    <Content fontFamily="secondary">
      
        We hold these truths to be self-evident, that all men are created
        equal...
      
    </Content>
  </Box>
  <Box>
    <Content fontFamily="code">
      
        We hold these truths to be self-evident, that all men are created
        equal...
      
    </Content>
  </Box>
</>
```

### Visibility

Show three buttons, one hidden, one screen-reader only:

```tsx live
<Buttons>
  <Button visibility="hidden">Hidden</Button>
  <Button visibility="sr-only">Screen Reader Only</Button>
  <Button>Visible</Button>
</Buttons>
```

### Overflow

Show a Box with clipped overflow:

```tsx live
<Box overflow="clipped" style={{ width: 200, height: 50 }}>
  This is a very long line of text that will be clipped and not overflow the
  box.
</Box>
```

### Overlay

Show an overlay (toggle with button click):

```tsx
function OverlayExample() {
  const [show, setShow] = useState(false);
  return (
    <Box overlay={show}>
      <Button onClick={() => setShow(s => !s)}>
        {show ? 'Hide Overlay' : 'Show Overlay'}
      </Button>
    </Box>
  );
}
```

### Interaction

Show text in a Box with `unselectable`, and another Box with `clickable`:

```tsx live
<>
  <Box interaction="unselectable">This text cannot be selected.</Box>
  <Box interaction="clickable">This box is clickable.</Box>
</>
```

### Cursor

Use the `cursor` prop to set the cursor style. `'pointer'` reuses Bulma's `is-clickable` class, while `'help'` uses the project-level `is-cursor-help` class:

```tsx live
<>
  <Box cursor="pointer">Cursor: pointer (uses is-clickable)</Box>
  <Box cursor="help">Cursor: help</Box>
</>
```

### Radius

Show buttons with `radiusless`:

```tsx live
<Buttons>
  <Button radius="radiusless">Radiusless</Button>
  <Button>Normal</Button>
</Buttons>
```

### Shadowless

Show a Box with `shadowless`:

```tsx live
<Box shadow="shadowless">This box has no shadow.</Box>
```

### ClassName

Show a Message with a custom className:

```tsx live
<Message className="custom-message">
  This message uses a custom className.
</Message>
```

### Clearfix

Show containers with and without clearfix to demonstrate the importance of clearing floated elements:

```tsx live
<>
  <Box>
    <Title size="6">Without clearfix (container collapses)</Title>
    <Notification color="danger">
      <Button float="left" color="primary">
        Left
      </Button>
      <Button float="right" color="danger">
        Right
      </Button>
    </Notification>
  </Box>

  <Box>
    <Title size="6">With clearfix (container wraps its floats)</Title>
    <Notification color="success" clearfix>
      <Button float="left" color="primary">
        Left
      </Button>
      <Button float="right" color="danger">
        Right
      </Button>
    </Notification>
  </Box>
</>
```

### Relative Position

Show a container with relative positioning that provides context for absolutely positioned children:

Bulma only ships an `is-relative` helper — absolute positioning itself has no helper class, so the child keeps a minimal `position/top/right` inline style while everything visual comes from props:

```tsx live
<Notification relative pb="6" color="info">
  This container has position: relative
  <Tag
    color="primary"
    size="medium"
    style={{ position: 'absolute', top: '1rem', right: '1rem' }}
  >
    Absolutely positioned child
  </Tag>
</Notification>
```

---

### Skeleton Examples

The `skeleton` prop applies Bulma's skeleton loading effect. Here are examples for each component:

#### Skeleton Button

```tsx live
<Button skeleton>Skeleton Button</Button>
```

#### Skeleton Buttons Group

```tsx live
<Buttons>
  <Button skeleton>Skeleton</Button>
  <Button skeleton>Skeleton</Button>
  <Button skeleton>Skeleton</Button>
</Buttons>
```

#### Skeleton Icon

```tsx live
<Icon name="star" skeleton ariaLabel="Star icon skeleton" />
```

#### Skeleton Image

```tsx live
<Image skeleton src="/img/react-logo.png" alt="Skeleton image" size="128x128" />
```

#### Skeleton Notification

```tsx live
<Notification skeleton>Skeleton notification message.</Notification>
```

#### Skeleton Tag

```tsx live
<Tag skeleton>Skeleton Tag</Tag>
```

#### Skeleton Title

```tsx live
<Title skeleton size="2">
  Skeleton Title
</Title>
```

#### Skeleton SubTitle

```tsx live
<SubTitle skeleton size="4">
  Skeleton SubTitle
</SubTitle>
```

#### Skeleton Input

```tsx live
<Input skeleton placeholder="Skeleton Input" />
```

#### Skeleton TextArea

```tsx live
<TextArea skeleton placeholder="Skeleton TextArea" rows={3} />
```

---

## Responsive Design

### Global Viewport Property (Legacy)

The `viewport` prop applies a single viewport modifier to ALL properties that support it:

```tsx
const { bulmaHelperClasses } = useBulmaClasses({
  color: 'primary',
  textAlign: 'centered',
  textSize: '4',
  viewport: 'mobile', // Applies -mobile to ALL properties
});
// Result: has-text-primary-mobile has-text-centered-mobile is-size-4-mobile
```

### Viewport-Specific Properties (Recommended)

Viewport-specific properties allow you to set **different values for each viewport**:

```tsx
const { bulmaHelperClasses } = useBulmaClasses({
  // Different text sizes for each viewport
  textSizeMobile: '6', // Small on mobile
  textSizeTablet: '5', // Medium on tablet
  textSizeDesktop: '4', // Large on desktop

  // Different text alignment for each viewport
  textAlignMobile: 'centered', // Center on mobile
  textAlignDesktop: 'left', // Left align on desktop

  // Different visibility for each viewport
  visibilityMobile: 'hidden', // Hidden on mobile
  visibilityTablet: 'invisible', // Invisible on tablet
});
// Result: is-size-6-mobile is-size-5-tablet is-size-4-desktop
//         has-text-centered-mobile has-text-left-desktop is-hidden-mobile is-invisible-tablet
```

### Breakpoint Reference

Bulma's responsive breakpoints:

- **mobile**: up to 768px
- **tablet**: 769px - 1023px
- **desktop**: 1024px - 1215px
- **widescreen**: 1216px - 1407px
- **fullhd**: 1408px and above

### Properties That Support Viewport Modifiers

Only certain properties support responsive variants:

**✅ Support Viewport Modifiers:**

- Text size (`textSize`, `textSizeMobile`, `textSizeTablet`, etc.)
- Text alignment (`textAlign`, `textAlignMobile`, `textAlignTablet`, etc.)
- Display (`display`, `displayMobile`, `displayTablet`, etc.)
- Visibility (`visibility`, `visibilityMobile`, `visibilityTablet`, etc.)

**❌ Do NOT Support Viewport Modifiers:**

- Spacing (`m`, `mt`, `mr`, `mb`, `ml`, `mx`, `my`, `p`, `pt`, `pr`, `pb`, `pl`, `px`, `py`)
- Background colors (`backgroundColor`)
- Flexbox properties (`flexDirection`, `flexWrap`, `justifyContent`, etc.)
- Other helpers (`float`, `clearfix`, `relative`, `borderRadius`, `shadow`, etc.)

---

## Notes

- Any prop not recognized as a Bulma helper prop is passed through in `rest`.
- Responsive helper props (`viewport`) suffix classes with the breakpoint (e.g., `is-size-3-mobile`).
- You can use in combination with [`classNames`](./classnames.md) for more advanced use.

---

## See Also

- [classNames helper](./classnames.md)
- [Bulma Classes Reference](https://bulma.io/documentation/helpers/)
- [Storybook: useBulmaClasses Demo](https://bestax.io/storybook/?path=/story/helpers-usebulmaclasses--default)

---

## Container


## Overview

The `Container` component provides a responsive and flexible layout wrapper for your Bulma React UI. It supports all Bulma container features, including fixed and fluid layouts, different breakpoints, widescreen/fullhd options, and helper props for colors, spacing, and more. It is typically used to center and constrain content horizontally within your page.

:::tip
Use `Container` to ensure your content maintains consistent margins and maximum width across different devices and breakpoints.
:::

---

## Import

```tsx

```

---

## Props

| Prop         | Type                                                                                                                                                                                                                                                                                     | Default | Description                                                                       |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------- |
| `fluid`      | `boolean`                                                                                                                                                                                                                                                                                | `false` | Makes the container full-width with a 32px gap on each side.                      |
| `widescreen` | `boolean`                                                                                                                                                                                                                                                                                | `false` | Makes the container full-width until the `widescreen` breakpoint.                 |
| `fullhd`     | `boolean`                                                                                                                                                                                                                                                                                | `false` | Makes the container full-width until the `fullhd` breakpoint.                     |
| `breakpoint` | `'tablet' \| 'desktop' \| 'widescreen'`                                                                                                                                                                                                                                                  | —       | Responsive breakpoint for container (`is-tablet`, `is-desktop`, `is-widescreen`). |
| `isMax`      | `boolean`                                                                                                                                                                                                                                                                                | `false` | Uses Bulma's `is-max-*` class for the specified breakpoint, limiting max width.   |
| `color`      | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger'`                                                                                                                                                                                                                    | —       | Bulma color modifier for text.                                                    |
| `textColor`  | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Text color helper.                                                                |
| `bgColor`    | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Background color helper.                                                          |
| `className`  | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                                                           |
| `children`   | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Content inside the container.                                                     |
| ...          | All standard `` and Bulma helper props                                                                                                                                                                                                                                              |         | (See [Helper Props](../helpers/usebulmaclasses))                                  |

---

## Usage

### Default Container

This example shows the `Container` component, which centers and constrains content horizontally. Use the `Container` to maintain consistent margins and maximum width for your content on desktop viewports and up.

```tsx live
<Container>
  <Notification color="primary">
    By default the container is centered on desktop viewports
    and up.
  </Notification>
</Container>
```

---

### Widescreen Container

Set the `widescreen` prop to make the container full-width until the `widescreen` breakpoint. This is useful for layouts that need to expand on larger screens.

```tsx live
<Container widescreen>
  <Notification color="primary">
    If <code>breakpoint="widescreen"</code> the container is{' '}
    fullwidth until the <code>widescreen</code>{' '}
    breakpoint.
  </Notification>
</Container>
```

---

### FullHD Container

Set the `fullhd` prop to make the container full-width until the `fullhd` breakpoint. Use this for layouts that need to take advantage of very large screens.

```tsx live
<Container fullhd>
  <Notification color="primary">
    If <code>breakpoint="fullhd"</code> the container is{' '}
    fullwidth until the <code>fullhd</code>{' '}
    breakpoint.
  </Notification>
</Container>
```

---

### Max Tablet Width

This example demonstrates using the `breakpoint` and `isMax` props together. Setting `breakpoint="tablet"` and `isMax` will limit the container's maximum width to that of the tablet size, minus the container offset.

```tsx live
<Container breakpoint="tablet" isMax>
  <Notification color="primary">
    If the container has <code>breakpoint="tablet"</code> and <code>isMax</code>{' '}
    then the container will have a <code>max-width</code> of{' '}
    <code>tablet - container offset</code>.
  </Notification>
</Container>
```

---

### Max Width Desktop

Similarly, this example sets the `breakpoint` to `desktop` with the `isMax` prop. The container's width will be constrained to the desktop size at this breakpoint.

```tsx live
<Container breakpoint="desktop" isMax>
  <Notification color="primary">
    If the container has <code>breakpoint="desktop"</code> and{' '}
    <code>isMax</code> then the container will have a <code>max-width</code> of{' '}
    <code>desktop - container offset</code>.
  </Notification>
</Container>
```

---

### Max Width Widescreen

For widescreen layouts, set the `breakpoint` to `widescreen` with `isMax`. This restricts the container's width to the widescreen size at the widescreen breakpoint.

```tsx live
<Container breakpoint="widescreen" isMax>
  <Notification color="primary">
    If the container has <code>breakpoint="widescreen"</code> and{' '}
    <code>isMax</code> then the container will have a <code>max-width</code> of{' '}
    <code>widescreen - container offset</code>.
  </Notification>
</Container>
```

---

### Fluid Container

The `fluid` prop makes the container expand to the full width of the screen, with a small 32px gap on each side. This is ideal for creating full-width sections with consistent padding.

```tsx live
<Container fluid>
  <Notification color="primary">
    If the container has <code>fluid</code> it will expand to the full width of
    the screen, with a small 32px gap on each side.
  </Notification>
</Container>
```

---

## Accessibility

- The container renders as a semantic `` by default.
- Use semantic HTML and accessible children within the container for best practices.

---

## Related Components

- [`Notification`](../elements/notification.md): Useful for demonstrating container layouts.
- [Helper Props](../helpers/usebulmaclasses.md): List of all supported Bulma helper props for spacing, colors, etc.

---

## Additional Resources

- [Bulma Container Documentation](https://bulma.io/documentation/layout/container/)
- [Storybook: Container Stories](https://bestax.io/storybook/?path=/story/layout-container--default)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Container />` for powerful utility-based styling.
:::

---

## Footer


## Overview

The `Footer` component provides a semantic and accessible site footer for your Bulma React UI. It supports Bulma color and background helpers, accepts any content as children, and can be rendered as either a `<footer>` or ``. Use it to display copyright, links, or extra information at the bottom of your pages.

:::info
`Footer` is usually placed at the end of your layout and is styled to stand out as a distinct section.
:::

---

## Import

```tsx

```

---

## Props

| Field       | Type                                                                                                                                                                                                                                                                                     | Default    | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------------------------------------------------ |
| `as`        | `'footer'` \| `'div'`                                                                                                                                                                                                                                                                    | `'footer'` | The HTML tag to render as.                       |
| `color`     | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —          | Bulma color modifier.                            |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —          | Background color.                                |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —          | Text color.                                      |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —          | Additional CSS classes.                          |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —          | Content inside the footer.                       |
| ...         | All Bulma helper and HTML props                                                                                                                                                                                                                                                          | —          | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Footer

This example shows the `Footer` component with centered content. Use the `Footer` at the bottom of your layout to display copyright, links, or extra information. The `as` prop can be used to render as a `<footer>` or ``.

```tsx live

<Footer>
  <Content textAlign="centered">
    <Paragraph>
      Bestax a Bulma component library by{' '}
      Alex Smith.
      MIT Source Code License
      {', '}
      Web content licensed{' '}
      
        CC BY NC SA 4.0
      
      .
    </Paragraph>
  </Content>
</Footer>;
```

---

## Accessibility

- Renders as a semantic `<footer>` tag by default.
- Accepts any valid children; ensure your links and text are accessible.
- You can use the `as="div"` prop if you need a non-semantic container.

:::note
When using only icons or non-text content, add `aria-label` or screen-reader-only content for accessibility.
:::

---

## Related Components

- [`Content`](../elements/content.md): For rich text and formatting within the footer.
- [`Container`](./container.md): To constrain footer width if desired.
- [Helper Props](../helpers/usebulmaclasses.md): Use Bulma utility helpers for spacing, color, etc.

---

## Additional Resources

- [Bulma Footer Documentation](https://bulma.io/documentation/layout/footer/)
- [Storybook: Footer Stories](https://bestax.io/storybook/?path=/story/layout-footer--default)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Footer />` for powerful utility-based styling.
:::

---

## Hero


## Overview

The `Hero` component provides a responsive, flexible, and visually striking section for your Bulma React UI. It supports all Bulma hero color and size modifiers, including fullheight, background helpers, and composition with `Hero.Head`, `Hero.Body`, and `Hero.Foot` subcomponents. Use it to showcase prominent content, headers, or landing sections.

:::info
You can use `Hero` as a simple colored banner, or compose it with `Hero.Head`, `Hero.Body`, and `Hero.Foot` for complex layouts with navigation, content, and tabs.
:::

---

## Import

```tsx

```

---

## Props

| Prop                   | Type                                                                                                                                                                                                                                                                                     | Default | Description                                                          |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------- |
| `color`                | `'primary' \| 'link' \| 'info' \| 'success' \| 'warning' \| 'danger' \| ...`                                                                                                                                                                                                             | —       | Bulma color modifier for the hero section.                           |
| `size`                 | `'small' \| 'medium' \| 'large' \| 'fullheight' \| 'fullheight-with-navbar'`                                                                                                                                                                                                             | —       | Hero size.                                                           |
| `fullheightWithNavbar` | `boolean`                                                                                                                                                                                                                                                                                | `false` | Use fullheight hero with a navbar offset.                            |
| `bgColor`              | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Bulma background color helper.                                       |
| `className`            | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                                              |
| `children`             | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Hero content (often includes `Hero.Head`, `Hero.Body`, `Hero.Foot`). |
| ...                    | All standard HTML and Bulma helper props                                                                                                                                                                                                                                                 |         | (See [Helper Props](../helpers/usebulmaclasses))                     |

**Subcomponents:**

- `Hero.Head`: Top bar for navigation or branding.
- `Hero.Body`: Main content area, vertically centered by default.
- `Hero.Foot`: Bottom bar for tabs or actions.

---

## Usage

### Default Hero

This example shows a standard `Hero` component with a centered title and subtitle. Use the `Hero` component to create visually striking banners or headers for your app. The `Hero.Body` subcomponent centers the content vertically.

```tsx live
<Hero>
  <Hero.Body>
    <Container>
      <Title>Hero title</Title>
      <SubTitle>Hero subtitle</SubTitle>
    </Container>
  </Hero.Body>
</Hero>
```

---

### All Colors

This example demonstrates the `color` prop, which applies Bulma color modifiers to the hero section. Use different `color` values to visually distinguish sections or indicate context.

```tsx live
<>
  <Hero color="link">
    <Hero.Body>
      <Container>
        <Title>Hero title (link)</Title>
        <SubTitle>Hero subtitle (link)</SubTitle>
      </Container>
    </Hero.Body>
  </Hero>
  <Hero color="primary">
    <Hero.Body>
      <Container>
        <Title>Hero title (primary)</Title>
        <SubTitle>Hero subtitle (primary)</SubTitle>
      </Container>
    </Hero.Body>
  </Hero>
  <Hero color="info">
    <Hero.Body>
      <Container>
        <Title>Hero title (info)</Title>
        <SubTitle>Hero subtitle (info)</SubTitle>
      </Container>
    </Hero.Body>
  </Hero>
  <Hero color="success">
    <Hero.Body>
      <Container>
        <Title>Hero title (success)</Title>
        <SubTitle>Hero subtitle (success)</SubTitle>
      </Container>
    </Hero.Body>
  </Hero>
  <Hero color="warning">
    <Hero.Body>
      <Container>
        <Title>Hero title (warning)</Title>
        <SubTitle>Hero subtitle (warning)</SubTitle>
      </Container>
    </Hero.Body>
  </Hero>
  <Hero color="danger">
    <Hero.Body>
      <Container>
        <Title>Hero title (danger)</Title>
        <SubTitle>Hero subtitle (danger)</SubTitle>
      </Container>
    </Hero.Body>
  </Hero>
</>
```

---

### All Sizes

This example showcases the `size` prop to demonstrate the different predefined hero sizes. Combine with the `color` prop for varied visual effects.

```tsx live
<>
  <Hero color="info" size="small">
    <Hero.Body>
      <Container>
        <Title>Hero title (small)</Title>
        <SubTitle>Hero subtitle (small)</SubTitle>
      </Container>
    </Hero.Body>
  </Hero>
  <Hero color="primary" size="medium">
    <Hero.Body>
      <Container>
        <Title>Hero title (medium)</Title>
        <SubTitle>Hero subtitle (medium)</SubTitle>
      </Container>
    </Hero.Body>
  </Hero>
  <Hero color="success" size="large">
    <Hero.Body>
      <Container>
        <Title>Hero title (large)</Title>
        <SubTitle>Hero subtitle (large)</SubTitle>
      </Container>
    </Hero.Body>
  </Hero>
  <Hero color="danger" size="fullheight">
    <Hero.Body>
      <Container>
        <Title>Hero title (fullheight)</Title>
        <SubTitle>Hero subtitle (fullheight)</SubTitle>
      </Container>
    </Hero.Body>
  </Hero>
</>
```

---

### Fullheight with Navbar

This example demonstrates using the `fullheightWithNavbar` prop to create a hero that takes the full height of the screen, adjusting for the height of the navbar. This is useful for landing pages or sections that require prominent visibility.

```tsx live
<>
  <Navbar>
    <Container>
      <Navbar.Menu id="navMenu">
        <Navbar.Start>
          <Navbar.Item as="a">Getting Started</Navbar.Item>
          <Navbar.Item as="a">APIs</Navbar.Item>
          <Navbar.Item as="a">Blog</Navbar.Item>
        </Navbar.Start>
        <Navbar.End>
          <Navbar.Item as="span">
            <Button color="primary" isInverted as="a" mx="2">
              Github
            </Button>
          </Navbar.Item>
        </Navbar.End>
      </Navbar.Menu>
    </Container>
  </Navbar>
  <Hero color="link" fullheightWithNavbar>
    <Hero.Body>
      <Container>
        <Title>Fullheight with navbar</Title>
      </Container>
    </Hero.Body>
  </Hero>
</>
```

---

### Fullheight with Head, Body, and Foot

This example shows a comprehensive usage of the `Hero` component with all its subcomponents: `Hero.Head`, `Hero.Body`, and `Hero.Foot`. It's a complete layout for a hero section, including navigation, main content, and footer tabs.

```tsx live
<Hero color="primary" size="medium">
  <Hero.Head>
    <Navbar>
      <Container>
        <Navbar.Brand>
          <Navbar.Item as="a">
            <Image src="/img/bestax-type-white.svg" alt="Bestax" mx="2" />
          </Navbar.Item>
          <Navbar.Burger />
        </Navbar.Brand>
        <Navbar.Menu id="navbarMenuHeroA">
          <Navbar.End>
            <Navbar.Item as="a" active>
              Getting Started
            </Navbar.Item>
            <Navbar.Item as="a">APIs</Navbar.Item>
            <Navbar.Item as="a">Blog</Navbar.Item>
            <Navbar.Item as="span">
              <Button color="primary" isInverted as="a" mx="2">
                <Icon
                  library="fa"
                  name="github"
                  variant="brands"
                  ariaLabel="github"
                />
                Github
              </Button>
            </Navbar.Item>
          </Navbar.End>
        </Navbar.Menu>
      </Container>
    </Navbar>
  </Hero.Head>

  <Hero.Body>
    <Container textAlign="centered">
      <Title>Bestax</Title>
      <SubTitle>A Bulma Component Library</SubTitle>
    </Container>
  </Hero.Body>

  <Hero.Foot>
    <Tabs>
      <Container>
        <Tabs.List>
          <Tabs.Item>
            Elements
          </Tabs.Item>
          <Tabs.Item>
            Components
          </Tabs.Item>
          <Tabs.Item>
            Columns
          </Tabs.Item>
          <Tabs.Item>
            Grid
          </Tabs.Item>
          <Tabs.Item>
            Layout
          </Tabs.Item>
        </Tabs.List>
      </Container>
    </Tabs>
  </Hero.Foot>
</Hero>
```

---

## Accessibility

- The hero renders as a semantic `<section>` by default.
- Subcomponents use semantic `` for layout but you can use accessible children/content.
- Use headings (`<Title>`, `<SubTitle>`) for best screen reader support.

:::note
When using fullheight or fullheight-with-navbar, ensure your layout remains keyboard navigable and visually accessible.
:::

---

## Related Components

- [`Container`](./container.md): To constrain content width inside the hero section.
- [`Navbar`](../components/navbar.md): For navigation in the `Hero.Head`.
- [`Tabs`](../components/tabs.md): For tabs in the `Hero.Foot`.
- [`Button`](../elements/button.md), [`Title`](../elements/title.md), [`SubTitle`](../elements/subtitle.md): For content and actions in the hero.
- [Helper Props](../helpers/usebulmaclasses.md): Use Bulma utility helpers for spacing, color, etc.

---

## Additional Resources

- [Bulma Hero Documentation](https://bulma.io/documentation/layout/hero/)
- [Storybook: Hero Stories](https://bestax.io/storybook/?path=/story/layout-hero--default)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Hero />` and its subcomponents for utility-based styling.
:::

---

## Level


## Overview

The `Level` component provides a flexible horizontal layout for your Bulma React UI, perfect for aligning items on the left and right, distributing items evenly, or centering statistics and controls. It supports Bulma color and background helpers, mobile responsiveness, and has subcomponents for left, right, and item sections.

:::info
Use `Level` for toolbars, status bars, or summary sections where you want to align content at the start, center, and end of a horizontal row.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                                |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------- |
| `isMobile`  | `boolean`                                                                                                                                                                                                                                                                                | `false` | Enables mobile layout (stacks vertically on mobile).       |
| `color`     | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Bulma color modifier for the level.                        |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Bulma background color helper.                             |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Bulma text color helper.                                   |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                                    |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Level content (`Level.Left`, `Level.Right`, `Level.Item`). |
| ...         | All standard HTML and Bulma helper props                                                                                                                                                                                                                                                 |         | (See [Helper Props](../helpers/usebulmaclasses))           |

**Subcomponents:**

- `Level.Left`: Left-aligned content.
- `Level.Right`: Right-aligned content.
- `Level.Item`: Individual item, can be rendered as `div`, `p`, or `a`.

---

## Usage

### Default Level

This example shows the `Level` component with `Level.Left` and `Level.Right` subcomponents. Use `Level` to align content horizontally, such as toolbars, status bars, or summary sections. The `Level.Item` subcomponent is used for each item in the left or right section.

```tsx live
<Level>
  <Level.Left>
    <Level.Item>
      <SubTitle as="p" size="5">
        Favorite Posts
      </SubTitle>
    </Level.Item>
    <Level.Item>
      <Field hasAddons>
        <Control>
          <Input type="text" placeholder="Find a post" />
        </Control>
        <Control>
          <Button>Search</Button>
        </Control>
      </Field>
    </Level.Item>
  </Level.Left>
  <Level.Right>
    <Level.Item as="p">
      All
    </Level.Item>
    <Level.Item as="p">
      <Link>Published</Link>
    </Level.Item>
    <Level.Item as="p">
      <Link>Drafts</Link>
    </Level.Item>
    <Level.Item as="p">
      <Link>Deleted</Link>
    </Level.Item>
    <Level.Item as="p">
      <Button color="success" as="a">
        New
      </Button>
    </Level.Item>
  </Level.Right>
</Level>
```

---

### Centered Level (Statistics)

This example demonstrates using the `Level` component to create a centered statistics display. Each `Level.Item` in this example is centered and contains a heading and a value, making it suitable for displaying key metrics or statistics.

```tsx live
<Level>
  <Level.Item hasTextCentered>
    <Block>
      <Paragraph className="heading">Posts</Paragraph>
      <Title as="p">1,234</Title>
    </Block>
  </Level.Item>
  <Level.Item hasTextCentered>
    <Block>
      <Paragraph className="heading">Following</Paragraph>
      <Title as="p">6789</Title>
    </Block>
  </Level.Item>
  <Level.Item hasTextCentered>
    <Block>
      <Paragraph className="heading">Followers</Paragraph>
      <Title as="p">123K</Title>
    </Block>
  </Level.Item>
  <Level.Item hasTextCentered>
    <Block>
      <Paragraph className="heading">Likes</Paragraph>
      <Title as="p">9876</Title>
    </Block>
  </Level.Item>
</Level>
```

---

### Centered Level Menu

This example shows how to create a centered navigation menu using the `Level` component. Each item in the menu is centered and can be used for navigation links or important actions.

```tsx live
<Level>
  <Level.Item as="p" hasTextCentered>
    <Link textColor="info">Getting Started</Link>
  </Level.Item>
  <Level.Item as="p" hasTextCentered>
    <Link textColor="info">APIs</Link>
  </Level.Item>
  <Level.Item as="p" hasTextCentered>
    
  </Level.Item>
  <Level.Item as="p" hasTextCentered>
    <Link textColor="info">Versions</Link>
  </Level.Item>
  <Level.Item as="p" hasTextCentered>
    <Link textColor="info">FAQ</Link>
  </Level.Item>
</Level>
```

---

### Mobile Level

This example demonstrates the `Level` component's mobile layout. When the `isMobile` prop is set, the `Level` component stacks its items vertically, making it suitable for mobile interfaces.

```tsx live
<Level isMobile>
  <Level.Item hasTextCentered>
    <Block>
      <Paragraph className="heading">Posts</Paragraph>
      <Title as="p">1,234</Title>
    </Block>
  </Level.Item>
  <Level.Item hasTextCentered>
    <Block>
      <Paragraph className="heading">Following</Paragraph>
      <Title as="p">4567</Title>
    </Block>
  </Level.Item>
  <Level.Item hasTextCentered>
    <Block>
      <Paragraph className="heading">Followers</Paragraph>
      <Title as="p">123K</Title>
    </Block>
  </Level.Item>
  <Level.Item hasTextCentered>
    <Block>
      <Paragraph className="heading">Likes</Paragraph>
      <Title as="p">9876</Title>
    </Block>
  </Level.Item>
</Level>
```

---

## Accessibility

- The root `Level` renders as a semantic `<nav>` for grouping and navigation.
- Items can be rendered as ``, ``, or ``. Use `as="a"` for links, and provide clear text or accessible labels.
- Use Bulma helper props for spacing and color to improve contrast and readability.

:::note
For best accessibility, use semantic elements for headings/content within items, and ensure interactive elements (like `Button` or links) are focusable and labeled.
:::

---

## Related Components

- [`Button`](../elements/button.md): Often used inside `Level.Item`.
- [`Title`](../elements/title.md): For headings/statistics in level items.
- [`Field`](../form/field.md) and [`Input`](../form/input.md): For search bars or controls in toolbars.
- [Helper Props](../helpers/usebulmaclasses.md): Use Bulma utility helpers for spacing, color, etc.

---

## Additional Resources

- [Bulma Level Documentation](https://bulma.io/documentation/layout/level/)
- [Storybook: Level Stories](https://bestax.io/storybook/?path=/story/layout-level--default)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Level />`, `<Level.Left>`, `<Level.Right>`, and `<Level.Item>` for powerful utility-based styling.
:::

---

## Media


## Overview

The `Media` component implements Bulma’s powerful media object layout for React. It’s perfect for aligning images or icons (usually on the left), with content and actions in the center and right. `Media` supports nesting, Bulma color/background helpers, and comes with subcomponents for left, content, and right sections.

:::info
Use `Media` for comments, posts, cards, notifications, or any structured block with media, text, and actions.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default     | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------ |
| `as`        | `'article'` \| `'div'`                                                                                                                                                                                                                                                                   | `'article'` | Element type for the root Media container.       |
| `color`     | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —           | Bulma color modifier.                            |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —           | Bulma background color helper.                   |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —           | Bulma text color helper.                         |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —           | Additional CSS classes.                          |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —           | Content inside the media container.              |
| ...         | All standard HTML and Bulma helper props                                                                                                                                                                                                                                                 |             | (See [Helper Props](../helpers/usebulmaclasses)) |

**Subcomponents:**

- `Media.Left`: For avatars, thumbnails, icons (renders as `figure` or `div`)
- `Media.Content`: Main content (renders as `div`)
- `Media.Right`: Actions or controls (renders as `div`)

---

## Usage

### Default Media

This example demonstrates the `Media` component with its subcomponents: `Media.Left` for an image or icon, `Media.Content` for the main content, and `Media.Right` for actions or controls. Use this pattern for comments, posts, or any layout that requires media and content alignment.

```tsx live
<Media>
  <Media.Left>
    <Image
      as="p"
      size="64x64"
      src="https://bulma.io/assets/images/placeholders/128x128.png"
      alt=""
    />
  </Media.Left>
  <Media.Content>
    <Content>
      <Paragraph>
        Alexander Hamilton <small>@hamilton</small>{' '}
        <small>31m</small>
        
        If men were angels, no government would be necessary. If angels were to
        govern men, neither external nor internal controls on government would
        be necessary.
      </Paragraph>
    </Content>
    <Level isMobile>
      <Level.Left>
        <Level.Item as="a">
          <Icon name="reply" variant="solid" size="small" />
        </Level.Item>
        <Level.Item as="a">
          <Icon name="retweet" variant="solid" size="small" />
        </Level.Item>
        <Level.Item as="a">
          <Icon name="heart" variant="solid" size="small" />
        </Level.Item>
      </Level.Left>
    </Level>
  </Media.Content>
  <Media.Right>
    <Delete aria-label="delete" />
  </Media.Right>
</Media>
```

---

### Media With Inputs

This example shows the `Media` component used with form inputs. The `Media.Content` section contains a `TextArea` for input and a `Button` for submission. This pattern is useful for comment sections or any interactive content area.

```tsx live
<Media>
  <Media.Left>
    <Image
      as="p"
      size="64x64"
      src="https://bulma.io/assets/images/placeholders/128x128.png"
      alt=""
    />
  </Media.Left>
  <Media.Content>
    <Field>
      <Control as="p">
        <TextArea placeholder="Add a comment..." />
      </Control>
    </Field>
    <Level>
      <Level.Left>
        <Level.Item>
          <Button as="a" color="info">
            Submit
          </Button>
        </Level.Item>
      </Level.Left>
      <Level.Right>
        <Level.Item>
          <Checkbox>Press enter to submit</Checkbox>
        </Level.Item>
      </Level.Right>
    </Level>
  </Media.Content>
</Media>
```

---

### Nested Media

Demonstrates the `Media` component's ability to nest for threaded comments or related content. Each `Media` component can contain its own `Media.Left`, `Media.Content`, and `Media.Right`, allowing for complex layouts.

```tsx live
<Media>
  <Media.Left>
    <Image
      as="p"
      size="64x64"
      src="https://bulma.io/assets/images/placeholders/128x128.png"
      alt=""
    />
  </Media.Left>
  <Media.Content>
    <Content>
      <Paragraph>
        John Jay
        
        The people, in their collective capacity, are the ultimate authority.
        The Union is essential to the security of the people of America against
        foreign danger.
        
        <small>
          Like &middot; Reply &middot; 3 hrs
        </small>
      </Paragraph>
    </Content>
    {/* First nested media */}
    <Media>
      <Media.Left>
        <Image
          as="p"
          size="48x48"
          src="https://bulma.io/assets/images/placeholders/96x96.png"
          alt=""
        />
      </Media.Left>
      <Media.Content>
        <Content>
          <Paragraph>
            James Madison
            
            The accumulation of all powers, legislative, executive, and
            judiciary, in the same hands, may justly be pronounced the very
            definition of tyranny.
            
            <small>
              Like &middot; Reply &middot; 2 hrs
            </small>
          </Paragraph>
        </Content>
        {/* 2nd nested media (two siblings) */}
        <Media>
          Experience has taught mankind the necessity of auxiliary precautions.
        </Media>
        <Media>Ambition must be made to counteract ambition.</Media>
      </Media.Content>
    </Media>
    {/* Second nested media */}
    <Media>
      <Media.Left>
        <Image
          as="p"
          size="48x48"
          src="https://bulma.io/assets/images/placeholders/96x96.png"
          alt=""
        />
      </Media.Left>
      <Media.Content>
        <Content>
          <Paragraph>
            Alexander Hamilton
            
            Safety from external danger is the most powerful director of
            national conduct. The desire for respect and security will always
            influence the policy of nations.
            
            <small>
              Like &middot; Reply &middot; 2 hrs
            </small>
          </Paragraph>
        </Content>
      </Media.Content>
    </Media>
  </Media.Content>
</Media>
```

---

### Media With Button Below

In this variation, a button is placed below the input area within the `Media.Content`. This layout can be used for comment submission or any action requiring a button.

```tsx live
<Media>
  <Media.Left>
    <Image
      as="p"
      size="64x64"
      src="https://bulma.io/assets/images/placeholders/128x128.png"
      alt=""
    />
  </Media.Left>
  <Media.Content>
    <Field>
      <Control as="p">
        <TextArea placeholder="Add a comment..." />
      </Control>
    </Field>
    <Field>
      <Control as="p">
        <Button>Post comment</Button>
      </Control>
    </Field>
  </Media.Content>
</Media>
```

---

## Accessibility

- The Media root renders as a semantic `<article>` by default. Use `as="div"` for a generic container.
- The left section is commonly used for avatars (as `<figure>`) and is screen-reader accessible.
- Use clear and descriptive text in content and actions for best accessibility.

:::note
When using only icons or controls, provide `aria-label` or screen-reader-only content as appropriate.
:::

---

## Related Components

- [`Level`](./level.md): For actions or stats inside the media content.
- [`Image`](../elements/image.md): For avatars or thumbnails.
- [`Button`](../elements/button.md), [`Checkbox`](../form/checkbox.md), [`TextArea`](../form/textarea.md): For interactive content.
- [Helper Props](../helpers/usebulmaclasses.md): Use Bulma utility helpers for spacing, color, etc.

---

## Additional Resources

- [Bulma Media Object Documentation](https://bulma.io/documentation/layout/media-object/)
- [Storybook: Media Stories](https://bestax.io/storybook/?path=/story/layout-media--default)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Media />` and its subcomponents for powerful utility-based styling.
:::

---

## Section


## Overview

The `Section` component provides vertical spacing and visual separation for your Bulma React UI. Use it to divide your page into large blocks of content, ensure consistent spacing, and apply Bulma helper props for color, background, and more. `Section` supports all Bulma section sizes and can be combined with containers, titles, and other layout components.

:::info
Use `Section` to break up your page into logical, visually distinct areas—such as headers, main content, and footers.
:::

---

## Import

```tsx

```

---

## Props

| Prop        | Type                                                                                                                                                                                                                                                                                     | Default | Description                                      |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------ |
| `size`      | `'medium'` \| `'large'`                                                                                                                                                                                                                                                                  | —       | Section size for extra vertical spacing.         |
| `color`     | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Bulma color modifier for text.                   |
| `bgColor`   | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Bulma background color helper.                   |
| `textColor` | `'primary'` \| `'link'` \| `'info'` \| `'success'` \| `'warning'` \| `'danger'` \| `'black'` \| `'black-bis'` \| `'black-ter'` \| `'grey-darker'` \| `'grey-dark'` \| `'grey'` \| `'grey-light'` \| `'grey-lighter'` \| `'white'` \| `'light'` \| `'dark'` \| `'inherit'` \| `'current'` | —       | Bulma text color helper.                         |
| `className` | `string`                                                                                                                                                                                                                                                                                 | —       | Additional CSS classes.                          |
| `children`  | `React.ReactNode`                                                                                                                                                                                                                                                                        | —       | Section content.                                 |
| ...         | All standard HTML and Bulma helper props                                                                                                                                                                                                                                                 |         | (See [Helper Props](../helpers/usebulmaclasses)) |

---

## Usage

### Default Section

This example shows a standard `Section` component, which provides vertical spacing and visual separation for your content. Use the `Section` component to break up your page into logical areas, such as headers, main content, or footers.

```tsx live
<Section>
  <Title>Section</Title>
  <SubTitle>
    Divide your content into into sections. Tada!
  </SubTitle>
</Section>
```

---

### Medium Section

Set the `size` prop to `"medium"` to increase the vertical spacing of the section. This is useful for visually emphasizing certain areas of your layout.

```tsx live
<Section size="medium">
  <Title>Medium Section</Title>
  <SubTitle>
    Divide your content into into sections. Tada! Make sure
    your window is wide or you won't see a medium section.
  </SubTitle>
</Section>
```

---

### Large Section

Set the `size` prop to `"large"` for even more vertical spacing. Use this for prominent page sections or to create clear separation between major content blocks.

```tsx live
<Section size="large">
  <Title>Large Section</Title>
  <SubTitle>
    Divide your content into into sections. Tada! Make sure
    your window is wide or you won't see a large section.
  </SubTitle>
</Section>
```

---

## Accessibility

- The section renders as a semantic `<section>` for improved structure and accessibility.
- Use headings (`<Title>`, `<SubTitle>`) and semantic content for screen reader support.

:::note
Sections help organize your document outline for screen readers and SEO.
:::

---

## Related Components

- [`Container`](./container.md): Nest inside a section to constrain content width.
- [`Title`](../elements/title.md), [`SubTitle`](../elements/subtitle.md): For headings and description in sections.
- [Helper Props](../helpers/usebulmaclasses.md): Use Bulma helper props for utility-based styling.

---

## Additional Resources

- [Bulma Section Documentation](https://bulma.io/documentation/layout/section/)
- [Storybook: Section Stories](https://bestax.io/storybook/?path=/story/layout-section--default)

:::tip Pro Tip
You can use all [Bulma helper props](../helpers/usebulmaclasses.md) with `<Section />` for powerful utility-based styling.
:::

---

## Bulma V1

# Bulma V1 (and Beyond)

bestax-bulma is built for **Bulma v1** — the version released in 2024 that introduced CSS custom properties, true CSS Grid, and skeleton loading — and it layers on a curated set of components Bulma doesn't ship. It's not a neutral wrapper around Bulma's markup; it's a React library that **extends** Bulma with the pieces real apps need (Carousel, Dialog, Autocomplete, Rate, Slider, Taginput, Toast, Sidebar, and more) while keeping the Bulma classes you already know.

## Why Bulma V1 Matters

Most React Bulma packages on npm still target Bulma v0.9.4. That means no CSS variables, no runtime theming, no true CSS Grid, no skeletons, and no class prefixing. Adopting any of them today means inheriting a design system frozen in 2023.

### Library Comparison

| Feature                     | Other Libraries          | bestax-bulma                                                                      |
| --------------------------- | ------------------------ | --------------------------------------------------------------------------------- |
| **Bulma Version**           | v0.9.4 or older          | v1.0+ (latest)                                                                    |
| **CSS Variables**           | ❌ Not supported         | ✅ Full support (500+ variables)                                                  |
| **Runtime Theming**         | ❌ Limited               | ✅ Complete `Theme` component                                                     |
| **CSS Grid**                | ❌ Missing               | ✅ True CSS Grid via `Grid` / `Cell`                                              |
| **Skeleton Loading**        | ❌ Not available         | ✅ Universal `skeleton` helper prop + dedicated `Skeleton` element                |
| **Class Prefixing**         | ❌ No support            | ✅ `ConfigProvider` support                                                       |
| **Dark Mode**               | ❌ Manual implementation | ✅ Built-in theme support                                                         |
| **Components beyond Bulma** | ❌ None                  | ✅ Carousel, Dialog, Autocomplete, Rate, Slider, Taginput, Toast, Sidebar, Switch |

## New Features in Bulma V1

### CSS Variables Support

Bulma v1 introduces comprehensive CSS custom properties, enabling runtime customization without Sass compilation:

```tsx

function RuntimeTheming() {
  return (
    <Theme primaryH="270" primaryS="100%" primaryL="50%" isRoot>
      <Box p="4">
        <Button color="primary">Purple themed button</Button>
      </Box>
    </Theme>
  );
}
```

**Benefits:**

- Change themes without rebuilding CSS
- User-customizable interfaces
- Dynamic color schemes
- Browser DevTools customization

### Configuration & Class Prefixing

Advanced configuration options for enterprise and multi-framework environments:

```tsx

function PrefixedApp() {
  return (
    <ConfigProvider classPrefix="bestax-">
      <Box>
        <Button color="primary">Prefixed button</Button>
      </Box>
    </ConfigProvider>
  );
}
```

**Use cases:**

- Framework integration (Bootstrap + Bulma)
- Multi-tenant applications
- Component library namespacing
- Legacy system integration

### Advanced Theming System

Complete theming capabilities with nested contexts and inheritance:

```tsx
function AdvancedTheming() {
  return (
    <Theme schemeH="210" schemeS="50%" isRoot>
      
        App-wide blue theme

        <Theme primaryH="120" primaryS="100%" primaryL="40%">
          <Box p="4">
            Green section
            <Button color="primary">Green button</Button>
          </Box>
        </Theme>

        <Button color="primary">Blue button</Button>
      
    </Theme>
  );
}
```

### True CSS Grid Support

**Important:** Bulma v0.9.4 referred to its flexbox-based column system as "grids," but they weren't true CSS Grid. Bulma v1 introduces actual CSS Grid support alongside the existing flexbox columns.

#### Smart Grid (Auto-responsive)

```tsx

function SmartGrid() {
  return (
    <Grid minCol={3} gap={2}>
      {[...Array(12)].map((_, i) => (
        <Cell key={i}>
          <Notification color="primary">Auto-sized cell {i + 1}</Notification>
        </Cell>
      ))}
    </Grid>
  );
}
```

#### Fixed Grid (Explicit columns)

```tsx
function FixedGrid() {
  return (
    <Grid
      isFixed
      fixedCols={4}
      fixedColsTablet={6}
      fixedColsDesktop={8}
      gap={3}
    >
      {[...Array(16)].map((_, i) => (
        <Cell key={i}>
          <Box p="3">
            <Button>Grid item {i + 1}</Button>
          </Box>
        </Cell>
      ))}
    </Grid>
  );
}
```

#### Grid vs Columns

```tsx
// Old: Flexbox "grid" (still available as Columns)
<Columns>
  <Column size="one-third">Column 1</Column>
  <Column size="one-third">Column 2</Column>
  <Column size="one-third">Column 3</Column>
</Columns>

// New: True CSS Grid
<Grid isFixed fixedCols={3}>
  <Cell>Cell 1</Cell>
  <Cell>Cell 2</Cell>
  <Cell>Cell 3</Cell>
</Grid>
```

### Skeleton Loading States

bestax exposes Bulma v1's skeletons through three complementary APIs:

1. **`skeleton` helper prop** — available on every component that uses `useBulmaClasses` (so: Button, Box, Icon, Image, Notification, Tag, Input, TextArea, and most others). Renders Bulma's `is-skeleton` class for an in-place loading state.
2. **`<Skeleton />` element** — a standalone placeholder for custom shapes and multi-line blocks (`<Skeleton variant="lines" lines={5} />`).
3. **`hasSkeleton` prop on `Title` / `SubTitle`** — emits `has-skeleton` so heading placeholders preserve the heading's sizing.

```tsx

  Box,
  Button,
  Title,
  Icon,
  Image,
  Skeleton,
} from '@allxsmith/bestax-bulma';

function SkeletonExamples() {
  const [loading, setLoading] = useState(true);

  return (
    <Box p="4">
      <Title hasSkeleton={loading}>
        {loading ? 'Loading...' : 'Content Loaded!'}
      </Title>

      <Button skeleton={loading} color="primary">
        Click me
      </Button>

      <Icon name="star" skeleton={loading} ariaLabel="Rating" />

      <Image
        skeleton={loading}
        src="https://via.placeholder.com/300"
        alt="Example"
        size="128x128"
      />

      {loading && <Skeleton variant="lines" lines={3} />}

      <button onClick={() => setLoading(!loading)}>Toggle Loading State</button>
    </Box>
  );
}
```

## Comprehensive Feature Matrix

### Elements

| Component        | Bulma v1 Features              | bestax-bulma Support |
| ---------------- | ------------------------------ | -------------------- |
| **Button**       | Skeleton states, CSS variables | ✅ Complete          |
| **Box**          | CSS variable theming           | ✅ Complete          |
| **Icon**         | Skeleton helper                | ✅ Complete          |
| **Image**        | Skeleton helper                | ✅ Complete          |
| **Notification** | CSS variable colors            | ✅ Complete          |
| **Progress**     | Enhanced animations            | ✅ Complete          |
| **Skeleton**     | Standalone placeholder element | ✅ Complete          |
| **Tag**          | Skeleton helper                | ✅ Complete          |
| **Title**        | `hasSkeleton` support          | ✅ Complete          |

### Components

| Component      | Bulma v1 Features    | bestax-bulma Support |
| -------------- | -------------------- | -------------------- |
| **Card**       | CSS variable theming | ✅ Complete          |
| **Dropdown**   | Enhanced positioning | ✅ Complete          |
| **Menu**       | CSS variable colors  | ✅ Complete          |
| **Message**    | Improved theming     | ✅ Complete          |
| **Modal**      | Enhanced styling     | ✅ Complete          |
| **Navbar**     | CSS variables        | ✅ Complete          |
| **Pagination** | Modern styling       | ✅ Complete          |
| **Tabs**       | Enhanced theming     | ✅ Complete          |

### Layout & Grid

| Feature             | Description               | Support     |
| ------------------- | ------------------------- | ----------- |
| **CSS Grid**        | True grid layout system   | ✅ Complete |
| **Smart Grid**      | Auto-responsive grids     | ✅ Complete |
| **Fixed Grid**      | Explicit column control   | ✅ Complete |
| **Grid Cells**      | Advanced cell positioning | ✅ Complete |
| **Flexbox Columns** | Legacy column system      | ✅ Complete |

### Modern Capabilities

| Feature              | Description                 | Implementation      |
| -------------------- | --------------------------- | ------------------- |
| **CSS Variables**    | 500+ customizable variables | Theme component     |
| **Runtime Theming**  | Dynamic theme switching     | Theme + CSS vars    |
| **Class Prefixing**  | Namespace CSS classes       | ConfigProvider      |
| **Dark Mode**        | Built-in dark theme support | Theme component     |
| **Skeleton Loading** | Loading state animations    | Component prop      |
| **Color Palettes**   | Extended color variations   | CSS variable shades |

## Beyond Bulma v1: bestax Extras

Bulma is a CSS framework — it doesn't ship carousels, dialogs, autocompletes, or rating inputs. bestax-bulma adds a curated set of React components that fit the same look and feel, use the same CSS variables, and respect the same `ConfigProvider` settings.

### Interactive components

| Component    | What it adds                                                |
| ------------ | ----------------------------------------------------------- |
| **Carousel** | Slide-based content viewer with auto-advance and indicators |
| **Dialog**   | Modal dialog with confirm/cancel callbacks                  |
| **Collapse** | Expandable content region with animation                    |
| **Sidebar**  | Slide-in navigation panel                                   |
| **Toast**    | Transient notification stack with optional action buttons   |
| **Loading**  | Full-page or in-box loading overlay                         |
| **Tooltip**  | Hover-triggered label with configurable delay               |

### Form components beyond Bulma

| Component        | What it adds                                                   |
| ---------------- | -------------------------------------------------------------- |
| **Autocomplete** | Searchable select with keyboard navigation                     |
| **Rate**         | Star-rating input                                              |
| **Slider**       | Themed range input                                             |
| **Taginput**     | Free-text tag entry                                            |
| **Switch**       | Toggle switch styled to match Bulma controls                   |
| **NumberInput**  | Numeric input with increment/decrement controls                |
| **Checkboxes**   | Grouped checkbox list with shared label / layout               |
| **Radios**       | Grouped radio list with shared label / layout                  |
| **Field**        | Convenience wrapper that bundles `Field` / `Control` / `Label` |

Each of these is a full React component with TypeScript types, Storybook examples, and its own API page under the **Components** and **Form** sections.

## Migration Benefits

### From Other Libraries

When migrating from other React Bulma libraries:

```tsx
// Before: Limited customization

<Button color="primary">Old library</Button>;

// After: Full Bulma v1 features

<ConfigProvider classPrefix="bestax-">
  <Theme primaryH="270" primaryS="100%" primaryL="50%">
    <Button color="primary" skeleton={loading}>
      Modern Bulma v1
    </Button>
  </Theme>
</ConfigProvider>;
```

### Performance Improvements

- Tree-shakeable imports
- Modern CSS with variables
- Efficient re-rendering with React contexts
- Smaller bundle sizes with modular imports

### Developer Experience

- Full TypeScript support
- Comprehensive prop interfaces
- Detailed documentation
- Storybook examples
- Modern React patterns

## Future-Proof Architecture

This library is designed to evolve with Bulma:

- **Continuous updates** with new Bulma releases
- **Backward compatibility** maintained
- **Modern React patterns** (hooks, contexts, etc.)
- **Performance optimizations** as standards evolve
- **Community-driven** development

## Getting Started with V1 Features

```tsx

  ConfigProvider,
  Theme,
  Grid,
  Cell,
  Button,
  Title,
} from '@allxsmith/bestax-bulma';

function ModernBulmaApp() {
  return (
    <ConfigProvider classPrefix="bestax-">
      <Theme primaryH="200" primaryS="100%" primaryL="50%" isRoot>
        <Grid minCol={2} gap={3}>
          <Cell>
            <Title skeleton={false}>Bulma V1 Features</Title>
            <Button color="primary" skeleton={false}>
              Modern Button
            </Button>
          </Cell>
          <Cell>
            <Button color="success">CSS Grid Layout</Button>
          </Cell>
        </Grid>
      </Theme>
    </ConfigProvider>
  );
}
```

This example uses class prefixing (`ConfigProvider`), runtime theming (`Theme`), and true CSS Grid (`Grid` / `Cell`) — all Bulma v1 features exposed as first-class React APIs.

### Why bestax-bulma

- **Latest Bulma v1** — not a v0.9.4 port.
- **TypeScript-first** — complete, accurate prop types for every component.
- **Tree-shakeable** — import only the components you use.
- **One dependency** — Bulma. bestax bundles it for you.
- **Extends, doesn't wrap** — Carousel, Dialog, Autocomplete, Rate, Slider, Taginput, Toast, Sidebar, and more are included alongside the full Bulma component set.

---

## Configuration


`ConfigProvider` is bestax-bulma's extension point for app-wide choices that Bulma itself can't express in React: a class-prefix namespace for the Bulma CSS classes your components emit, and a default icon library every `Icon` should fall back to. It works through React context, so any setting you provide applies to every descendant component — no prop drilling.

## Overview

`ConfigProvider` supports two settings today:

- **`classPrefix`** — prefix applied to every Bulma class name the library renders (pair it with the matching prefixed bestax CSS bundle, `@allxsmith/bestax-bulma/versions/bestax-prefixed.css`, for `classPrefix="bestax-"`).
- **`iconLibrary`** — the default icon library (`'fa'`, `'mdi'`, `'ion'`, `'material-icons'`, `'material-symbols'`) that `Icon` components resolve to when no `library` prop is set.

Both are optional; without a `ConfigProvider` the library uses unprefixed Bulma classes and Font Awesome icons.

## CSS Class Prefixing

Class prefixing adds a namespace to every Bulma class the library renders:

- `button` becomes `bestax-button`
- `box` becomes `bestax-box`
- `title` becomes `bestax-title`

The goal is to avoid collisions between Bulma's generic class names (`.button`, `.card`, `.title`, `.menu`, `.notification`, …) and the class names used by your own application's CSS. Teams that have their own hand-written stylesheets — design tokens, layout utilities, component classes — often already use some of those names; prefixing every Bulma class lets both sets coexist cleanly.

:::note Not for combining CSS frameworks
Class prefixing is about namespacing Bulma's class names, not about running bestax alongside another CSS framework like Bootstrap or Tailwind Preflight. Bulma's base-element rules (in `bulma/sass/base/minireset.scss` and `generic.scss`) target raw HTML tags — `body`, `p`, `h1`–`h6`, `ul`, `img`, `table`, … — and apply globally regardless of any class prefix. Stacking Bulma on top of another framework's reset is not a supported setup; pick one framework for the base layer.
:::

## Basic Usage

### Standard Configuration

```tsx

function App() {
  return (
    <ConfigProvider classPrefix="bestax-">
      <Box p="4">
        <Title size="4">Prefixed Components</Title>
        <Button color="primary">Prefixed Button</Button>
      </Box>
    </ConfigProvider>
  );
}
```

This renders HTML with prefixed CSS classes:

```html

  Prefixed Components
  <button class="bestax-button is-primary">Prefixed Button</button>

```

### Avoiding Conflicts With Your Own Stylesheets

If your application already ships its own CSS — a home-grown design system, marketing-page styles, vendored legacy stylesheets — odds are some of your selectors clash with Bulma's (`.button`, `.card`, `.title`, `.menu`, `.notification`, `.content`…). Prefixing every Bulma class keeps the two worlds distinct:

```tsx

function App() {
  return (
    <ConfigProvider classPrefix="bestax-">
      {/* bestax renders .bestax-button, .bestax-box, etc.
          Your app's own .button / .card rules are untouched. */}
      <Box p="4">
        <Title size="4">App section</Title>
        <Button color="primary">Action</Button>
      </Box>
    </ConfigProvider>
  );
}
```

## Default Icon Library

Every `Icon` component can resolve to a different icon library — Font Awesome, Material Design Icons, Ionicons, Material Icons, or Material Symbols. Setting `iconLibrary` on `ConfigProvider` lets the whole tree default to one library; individual `Icon` components can still override per-use.

```tsx

function App() {
  return (
    <ConfigProvider iconLibrary="mdi">
      <Button color="primary">
        <Icon name="rocket-launch" />
        Launch
      </Button>
    </ConfigProvider>
  );
}
```

Valid values are `'fa'` (Font Awesome), `'mdi'` (Material Design Icons), `'ion'` (Ionicons), `'material-icons'`, and `'material-symbols'`. This is the same choice `pnpm create bestax@latest` prompts for during project setup.

## Combining Prefix and Icon Library

Both settings are independent and compose. Set whichever you need:

```tsx
<ConfigProvider classPrefix="bestax-" iconLibrary="mdi">
  <App />
</ConfigProvider>
```

## Prefixed bestax CSS bundle

bestax ships a prebuilt, `bestax-`-prefixed bundle (Bulma **and** the bestax extras, all prefixed together) that pairs with `classPrefix="bestax-"`. Import it directly:

```tsx
// Prefixed bestax bundle (Bulma + extras, all "bestax-" prefixed)

function App() {
  return (
    <ConfigProvider classPrefix="bestax-">
      <Button color="primary">Uses bestax-button class</Button>
    </ConfigProvider>
  );
}
```

## Custom Prefix Builds

For teams building custom Bulma CSS with their own prefixes:

### 1. Install Dependencies

```bash
pnpm add bulma sass
```

### 2. Create Custom Sass File

```scss title="src/styles/mycompany-bulma.scss"
@use 'bulma/sass' with (
  $class-prefix: 'mycompany-'
);
```

### 3. Configure Your Application

```tsx title="src/App.tsx"

function App() {
  return (
    <ConfigProvider classPrefix="mycompany-">
      <Box>
        <Button color="primary">Custom Prefixed Button</Button>
      </Box>
    </ConfigProvider>
  );
}
```

## Advanced Configuration

### Nested Providers

ConfigProviders can be nested, with inner providers overriding outer settings:

```tsx
function NestedConfiguration() {
  return (
    <ConfigProvider classPrefix="outer-">
      <Box p="4">
        <Title>Outer Prefix (outer-)</Title>

        <ConfigProvider classPrefix="inner-">
          <Box p="4" mt="3">
            <Title>Inner Prefix (inner-)</Title>
            <Button color="primary">Inner Button</Button>
          </Box>
        </ConfigProvider>

        <Button color="info" mt="3">
          Outer Button
        </Button>
      </Box>
    </ConfigProvider>
  );
}
```

### Using Configuration in Custom Components

Your own components can participate in the same prefix/icon conventions as bestax's built-ins:

```tsx

function CustomComponent() {
  const prefixed = usePrefixedClass();
  return Custom content;
}
```

## Configuration Hooks

Four hooks expose the active configuration so your own components can honor the same settings as bestax's built-ins.

### useConfig

Returns the full configuration object:

```tsx

function MyComponent() {
  const { classPrefix, iconLibrary } = useConfig();
  // ...
}
```

### useClassPrefix

Convenience hook that returns just the class prefix as a string (empty string if none):

```tsx

function MyComponent() {
  const classPrefix = useClassPrefix();
}
```

### usePrefixedClass

Returns a function that applies the configured prefix to a class name — handy when building custom components that need to stay in sync with a prefixed Bulma build:

```tsx

function CustomBanner() {
  const prefixed = usePrefixedClass();
  // Renders "bestax-notification" under ConfigProvider classPrefix="bestax-",
  // or plain "notification" without a prefix.
  return Hello;
}
```

### useIconLibrary

Returns the configured icon library (or `undefined`):

```tsx

function MyIcon({ name }) {
  const library = useIconLibrary() ?? 'fa';
  // Render an icon using the configured library
}
```

## Use Cases

### Multi-tenant Applications

Different tenants can have different styling namespaces:

```tsx
function TenantApp({ tenantName }) {
  return (
    <ConfigProvider classPrefix={`${tenantName}-`}>
      <App />
    </ConfigProvider>
  );
}
```

### Component Library Wrapping

When building your own component library on top of bestax, give its Bulma classes a distinct namespace so they can't clash with anything a consumer adds:

```tsx
function MyLibraryProvider({ children }) {
  return <ConfigProvider classPrefix="mylib-">{children}</ConfigProvider>;
}
```

## Best Practices

1. **Set at the root level** — apply `ConfigProvider` once near the top of your tree; nest only when a subtree genuinely needs different settings.
2. **Match CSS and React** — if you set `classPrefix="bestax-"`, import the matching prefixed bestax bundle `@allxsmith/bestax-bulma/versions/bestax-prefixed.css` (or your own Sass build with the same prefix). Using the bestax bundle — rather than stock `bulma/css/...` plus a separate `extras.css` — keeps the bestax extra components (Notification, Tooltip, etc.) prefixed too.
3. **Match icon font and setting** — if you set `iconLibrary="mdi"`, make sure the MDI font package is imported somewhere in your app.
4. **Trust one source** — the `create-bestax` installer wires all of this up in a consistent way; reach for a custom `ConfigProvider` only when the defaults don't fit.

## Integration with Other Features

ConfigProvider works seamlessly with other library features:

```tsx
function CompleteSetup() {
  return (
    <ConfigProvider classPrefix="bestax-">
      <Theme primaryH="270" primaryS="100%" primaryL="50%" isRoot>
        <App />
      </Theme>
    </ConfigProvider>
  );
}
```

For detailed API documentation and more examples, see the [ConfigProvider API reference](../../api/helpers/config.md).

---

## CSS Variables


[Bulma v1 introduces comprehensive support for CSS custom properties (CSS variables)](https://bulma.io/documentation/features/css-variables/), enabling runtime customization without Sass compilation. bestax-bulma gives you a first-class React surface for all 500+ of them through the `Theme` component: named, camelCase props for the common variables, a `bulmaVars` escape hatch for the long tail, and automatic scoping so themes compose via React context — no manual style-sheet injection, no string concatenation, fully type-checked.

:::info Bulma's canonical reference
The authoritative documentation for every Bulma CSS variable lives on the Bulma site:

- [CSS Variables in Bulma](https://bulma.io/documentation/features/css-variables/) — how Bulma uses CSS variables and their `--bulma-` prefix.
- [Themes](https://bulma.io/documentation/features/themes/) — Bulma's theme system (a theme is a set of CSS variables scoped at `:root` or below).
- [Dark Mode](https://bulma.io/documentation/features/dark-mode/) — the prefers-color-scheme and `.theme-dark` conventions Bulma ships.

This page focuses on the React surface (`Theme`, `bulmaVars`); refer to Bulma's docs for the variable catalog and CSS-level semantics.
:::

## What are CSS Variables?

CSS variables (officially called CSS custom properties) are entities defined by CSS authors that contain specific values to be reused throughout a document. Unlike Sass variables, which are compile-time constants, CSS variables are runtime values that can be:

- Changed dynamically with JavaScript
- Inherited through the CSS cascade
- Scoped to specific DOM elements
- Modified without rebuilding your CSS

## Runtime Customization

### Browser DevTools

You can modify Bulma's appearance directly in browser developer tools by changing CSS variable values. This is powerful for testing and debugging:

**Steps to test:**

1. Open your browser's developer tools
2. Select the `html` element in the Elements panel
3. In the Styles panel, add or modify a CSS variable like `--bulma-primary-h: 270deg`
4. Watch the changes apply instantly across your entire application

```css
/* Example: Change primary color to purple in DevTools */
:root {
  --bulma-primary-h: 270deg;
  --bulma-primary-s: 100%;
  --bulma-primary-l: 50%;
}
```

### JavaScript Runtime Changes

CSS variables can be modified programmatically:

```javascript
// Change primary color dynamically
document.documentElement.style.setProperty('--bulma-primary-h', '120deg');

// Change theme scheme
document.documentElement.style.setProperty('--bulma-scheme-h', '210deg');
```

## Using the Theme Component

`Theme` is bestax's React wrapper for Bulma's CSS variables. Two things make it idiomatic to use from React rather than hand-writing `style.setProperty` calls:

- **Named props for the common variables** — `primaryH`, `schemeH`, `radius`, `familyPrimary`, etc. TypeScript autocompletes them and catches typos at build time.
- **`bulmaVars` for everything else** — a single object prop that accepts raw CSS variable names, so you never hit a ceiling.

Themes nest naturally: outer `<Theme>` sets app-wide defaults, inner ones scope overrides to a subtree. Use `isRoot` to inject variables at `:root` for true app-wide reach.

### Global Theme Application

```tsx

function App() {
  return (
    <Theme
      isRoot
      primaryH="270"
      primaryS="100%"
      primaryL="50%"
      schemeH="260"
      schemeS="30%"
    >
      <Box p="4">
        <Title>Purple-themed Application</Title>
        <Button color="primary">Purple Button</Button>
      </Box>
    </Theme>
  );
}
```

### Scoped Theme Application

```tsx
function ScopedTheming() {
  return (
    
      <Title>Standard Theme</Title>

      <Theme primaryH="120" primaryS="100%" primaryL="40%">
        <Box p="4" mt="3">
          <Title size="4">Green Section</Title>
          <Button color="primary">Green Button</Button>
        </Box>
      </Theme>

      <Theme primaryH="15" primaryS="85%" primaryL="55%">
        <Box p="4" mt="3">
          <Title size="4">Orange Section</Title>
          <Button color="primary">Orange Button</Button>
        </Box>
      </Theme>
    
  );
}
```

### Using bulmaVars Object

For less common variables or when you have many to set:

```tsx
function AdvancedTheming() {
  const customTheme = {
    '--bulma-family-primary': '"Helvetica Neue", sans-serif',
    '--bulma-family-code': '"Fira Code", monospace',
    '--bulma-size-normal': '16px',
    '--bulma-weight-bold': '700',
    '--bulma-title-color': 'hsl(0, 0%, 21%)',
    '--bulma-subtitle-color': 'hsl(0, 0%, 48%)',
    '--bulma-card-shadow': '0 8px 32px rgba(0, 0, 0, 0.1)',
    '--bulma-button-border-radius': '12px',
  };

  return (
    <Theme bulmaVars={customTheme}>
      <Box p="4">
        <Title>Custom Typography & Styling</Title>
        <Button color="primary">Custom Styled Button</Button>
      </Box>
    </Theme>
  );
}
```

## Complete CSS Variables Catalog

Bulma v1 provides 500+ CSS variables organized by category. Here are the key categories — for the full, authoritative list see the [Bulma CSS Variables reference](https://bulma.io/documentation/features/css-variables/) and the per-component pages under [bulma.io/documentation](https://bulma.io/documentation/).

### Scheme Variables

| Variable           | Description                | Example Value |
| ------------------ | -------------------------- | ------------- |
| `--bulma-scheme-h` | Base hue for color scheme  | `210`         |
| `--bulma-scheme-s` | Base saturation            | `50%`         |
| `--bulma-light-l`  | Light background lightness | `96%`         |
| `--bulma-dark-l`   | Dark background lightness  | `4%`          |
| `--bulma-soft-l`   | Soft color lightness       | `85%`         |
| `--bulma-bold-l`   | Bold color lightness       | `15%`         |

### Color Variables

| Variable            | Description              | Example Value |
| ------------------- | ------------------------ | ------------- |
| `--bulma-primary-h` | Primary color hue        | `171`         |
| `--bulma-primary-s` | Primary color saturation | `100%`        |
| `--bulma-primary-l` | Primary color lightness  | `41%`         |
| `--bulma-link-h`    | Link color hue           | `233`         |
| `--bulma-info-h`    | Info color hue           | `198`         |
| `--bulma-success-h` | Success color hue        | `153`         |
| `--bulma-warning-h` | Warning color hue        | `42`          |
| `--bulma-danger-h`  | Danger color hue         | `348`         |

### Typography Variables

| Variable                 | Description         | Example Value                                |
| ------------------------ | ------------------- | -------------------------------------------- |
| `--bulma-family-primary` | Primary font family | `'BlinkMacSystemFont', 'Segoe UI', 'Roboto'` |
| `--bulma-family-code`    | Code font family    | `'Source Code Pro', monospace`               |
| `--bulma-size-normal`    | Normal text size    | `1rem`                                       |
| `--bulma-weight-normal`  | Normal font weight  | `400`                                        |
| `--bulma-weight-bold`    | Bold font weight    | `700`                                        |

### Layout Variables

| Variable                 | Description           | Example Value |
| ------------------------ | --------------------- | ------------- |
| `--bulma-block-spacing`  | Block element spacing | `1.5rem`      |
| `--bulma-radius`         | Default border radius | `4px`         |
| `--bulma-radius-rounded` | Rounded border radius | `9999px`      |
| `--bulma-column-gap`     | Column spacing        | `0.75rem`     |
| `--bulma-grid-gap`       | Grid spacing          | `1rem`        |

### Component-Specific Variables

#### Button Variables

| Variable                               | Description               |
| -------------------------------------- | ------------------------- |
| `--bulma-button-padding-vertical`      | Button vertical padding   |
| `--bulma-button-padding-horizontal`    | Button horizontal padding |
| `--bulma-button-border-radius`         | Button border radius      |
| `--bulma-button-focus-box-shadow-size` | Focus shadow size         |

#### Card Variables

| Variable                        | Description        |
| ------------------------------- | ------------------ |
| `--bulma-card-color`            | Card text color    |
| `--bulma-card-background-color` | Card background    |
| `--bulma-card-shadow`           | Card drop shadow   |
| `--bulma-card-radius`           | Card border radius |

#### Input Variables

| Variable                          | Description                |
| --------------------------------- | -------------------------- |
| `--bulma-input-color-l`           | Input text lightness       |
| `--bulma-input-background-l`      | Input background lightness |
| `--bulma-input-border-l`          | Input border lightness     |
| `--bulma-input-focus-shadow-size` | Focus shadow size          |

## Dynamic Theming Examples

### Dark Mode Toggle

Bulma ships a built-in dark-mode scheme. The simplest way to drive it is the `Theme` component's
`colorMode` prop (`'light' | 'dark' | 'system'`), which writes Bulma's `data-theme` attribute on
`<html>` for you. `'system'` follows the OS `prefers-color-scheme`.

```tsx
function DarkModeApp() {
  const [mode, setMode] = useState<'light' | 'dark' | 'system'>('system');

  return (
    <Theme isRoot colorMode={mode}>
      <Box p="4">
        <Title>Dynamic Dark Mode</Title>
        <Button onClick={() => setMode('dark')} color="primary">
          Dark
        </Button>
        <Button onClick={() => setMode('light')} color="primary">
          Light
        </Button>
        <Button onClick={() => setMode('system')}>System</Button>
      </Box>
    </Theme>
  );
}
```

For full control you can instead override the scheme variables yourself via `bulmaVars` (e.g.
`--bulma-scheme-h`, `--bulma-light-l`, `--bulma-dark-l`), but `colorMode` covers the common case.

### Color Palette Generator

```tsx
function ColorPaletteApp() {
  const [hue, setHue] = useState(171);

  return (
    <Theme primaryH={hue.toString()} isRoot>
      <Box p="4">
        <Title>Dynamic Color Palette</Title>
        <input
          type="range"
          min="0"
          max="360"
          value={hue}
          onChange={e => setHue(parseInt(e.target.value))}
        />
        Hue: {hue}°

        
          <Button color="primary">Primary</Button>
          <Button color="info">Info</Button>
          <Button color="success">Success</Button>
          <Button color="warning">Warning</Button>
          <Button color="danger">Danger</Button>
        
      </Box>
    </Theme>
  );
}
```

## Advantages Over Sass Variables

### Build-time vs Runtime

```scss
/* Sass variables (build-time only) */
$primary: #ff6b35;
$family-primary: 'Helvetica Neue', sans-serif;

@import 'bulma/bulma.sass';
```

```css
/* CSS variables (runtime modifiable) */
:root {
  --bulma-primary-h: 18deg;
  --bulma-primary-s: 100%;
  --bulma-primary-l: 60%;
  --bulma-family-primary: '"Helvetica Neue", sans-serif';
}
```

### Benefits of CSS Variables

1. **Runtime modification**: Change themes without rebuilding CSS
2. **User preferences**: Allow users to customize appearance
3. **Context-aware theming**: Different themes for different sections
4. **Performance**: No need for multiple CSS bundles
5. **Testing**: Easy to test different color schemes
6. **Debugging**: Modify values in DevTools for instant feedback

## Best Practices

### Organization

Group related variables for better maintainability:

```tsx
const brandTheme = {
  // Brand colors
  '--bulma-primary-h': '210',
  '--bulma-primary-s': '100%',
  '--bulma-primary-l': '50%',

  // Typography
  '--bulma-family-primary': '"Inter", sans-serif',
  '--bulma-weight-normal': '400',
  '--bulma-weight-bold': '600',

  // Layout
  '--bulma-radius': '8px',
  '--bulma-block-spacing': '2rem',
};
```

### Scope

- Prefer a single `isRoot` `Theme` at the top of your tree for global values.
- Use nested, non-root `Theme` elements only to override a specific subtree (a dashboard section, a marketing block) — each non-root theme wraps its children in a ``, so don't nest one around a single button when a helper prop would do.

### Consistency

- Establish a design system with your CSS variables
- Document which variables your team uses most commonly
- Create reusable theme objects for common scenarios

## Further Reading

- [Theme component reference](../../api/helpers/theme.md) — the full bestax React API.
- [Bulma: CSS Variables](https://bulma.io/documentation/features/css-variables/) — how Bulma defines and consumes CSS variables.
- [Bulma: Themes](https://bulma.io/documentation/features/themes/) — Bulma's theme system and scoping rules.
- [Bulma: Dark Mode](https://bulma.io/documentation/features/dark-mode/) — dark-scheme conventions.
- [Bulma: Customize with CSS Variables](https://bulma.io/documentation/customize/with-css-variables/) — CSS-only customization guide.

---

## Responsiveness


This guide covers how Bestax components handle responsive design. Bestax extends Bulma with React components and additional UI on top of Bulma's CSS, so the responsive props and breakpoints you'll see here inherit directly from Bulma — you just drive them through Bestax's typed React API.

:::tip Test Responsive Behavior

Try resizing your browser window or using the responsive design mode in your browser's developer tools to see the responsive behavior in action. The live examples below demonstrate different behaviors across breakpoints: **mobile** (up to 768px), **tablet** (769px+), **desktop** (1024px+), **widescreen** (1216px+), and **fullhd** (1408px+).

:::

## Component Display Behavior

Many Bestax components inherit Bulma's mobile-first behavior, stacking vertically or going block-level by default on smaller screens so content stays accessible and readable.

### Vertical Components

These components automatically stack vertically on mobile:

- **Columns**: Individual columns stack vertically on mobile unless `isMobile` is specified
- **Level**: Level items stack vertically on mobile unless `isMobile` prop is used
- **Navbar**: Navbar items collapse into a burger menu on mobile

```tsx live
<>
  These will stack on mobile by default
  <Columns>
    <Column>
      <Notification color="primary">First column</Notification>
    </Column>
    <Column>
      <Notification color="info">Second column</Notification>
    </Column>
    <Column>
      <Notification color="success">Third column</Notification>
    </Column>
  </Columns>

  <Level>
    <LevelLeft>
      <LevelItem>Left content</LevelItem>
    </LevelLeft>
    <LevelRight>
      <LevelItem>Right content</LevelItem>
    </LevelRight>
  </Level>
</>
```

### Mobile Override

Use the `isMobile` property to maintain horizontal layout even on mobile devices:

```tsx live
<>
  Force horizontal layout on mobile
  <Columns isMobile>
    <Column>
      <Notification color="warning">Always</Notification>
    </Column>
    <Column>
      <Notification color="danger">Horizontal</Notification>
    </Column>
  </Columns>

  <Level isMobile>
    <LevelLeft>
      <LevelItem>Left</LevelItem>
    </LevelLeft>
    <LevelRight>
      <LevelItem>Right</LevelItem>
    </LevelRight>
  </Level>
</>
```

## Breakpoints

Bestax uses Bulma's 4 breakpoints to define 5 screen sizes:

| Size           | Range       | CSS Variable         |
| -------------- | ----------- | -------------------- |
| **mobile**     | up to 768px | --tablet: 769px      |
| **tablet**     | from 769px  | --desktop: 1024px    |
| **desktop**    | from 1024px | --widescreen: 1216px |
| **widescreen** | from 1216px | --fullhd: 1408px     |
| **fullhd**     | from 1408px | (no upper limit)     |

These breakpoints drive every responsive prop and helper class across Bestax.

## Container Responsiveness

The `Container` component provides responsive width constraints and breakpoint support:

### Breakpoint Properties

```tsx live
<>
  Standard container - centered on desktop+
  <Container>
    <Notification color="primary">Responsive container content</Notification>
  </Container>

  Tablet breakpoint - full width until tablet
  <Container breakpoint="tablet">
    <Notification color="info">
      Full width on mobile, constrained on tablet+
    </Notification>
  </Container>

  Desktop breakpoint - full width until desktop
  <Container breakpoint="desktop">
    <Notification color="success">Full width until desktop</Notification>
  </Container>

  Widescreen breakpoint - full width until widescreen
  <Container breakpoint="widescreen">
    <Notification color="warning">Full width until widescreen</Notification>
  </Container>
</>
```

### Maximum Width Constraints

Use `isMax` with breakpoints to limit container width:

```tsx live
<>
  Maximum tablet width
  <Container breakpoint="tablet" isMax>
    <Notification color="danger">
      Container width limited to tablet size minus container offset
    </Notification>
  </Container>

  Maximum desktop width
  <Container breakpoint="desktop" isMax>
    <Notification color="primary">
      Container width limited to desktop size minus container offset
    </Notification>
  </Container>

  Maximum widescreen width
  <Container breakpoint="widescreen" isMax>
    <Notification color="info">
      Container width limited to widescreen size minus container offset
    </Notification>
  </Container>
</>
```

### Fluid Containers

Fluid containers expand to full width with consistent padding:

```tsx live
<>
  Full width with 32px padding on each side
  <Container fluid>
    <Notification color="success">
      Full width container with small gaps on each side
    </Notification>
  </Container>
</>
```

### Widescreen and FullHD Options

Control when containers become constrained:

```tsx live
<>
  Full width until widescreen breakpoint
  <Container widescreen>
    <Notification color="warning">
      Expands until widescreen (1216px)
    </Notification>
  </Container>

  Full width until fullhd breakpoint
  <Container fullhd>
    <Notification color="danger">Expands until fullhd (1408px)</Notification>
  </Container>
</>
```

## Responsive Helper Classes

The `viewport` prop scopes a helper to a single breakpoint. It applies to typography and display helpers (`textAlign`, `textSize`, `display`, `visibility`); Bestax's spacing helpers (`m`, `p`, …) mirror Bulma's and don't have responsive variants, so `viewport` is a no-op on them.

### Text Alignment

```tsx live
<>
  Different text alignment per breakpoint
  <Box textAlign="left" viewport="mobile">
    Left aligned on mobile
  </Box>

  <Box textAlign="centered" viewport="tablet">
    Centered on tablet and up
  </Box>
</>
```

### Spacing

Bestax inherits Bulma's spacing system, which applies uniformly across breakpoints — there are no `mTablet` / `pDesktop` variants. To vary whitespace responsively, wrap content in breakpoint-aware containers or toggle `display` / `visibility` per viewport.

```tsx live
<>
  Uniform padding and margin at every breakpoint
  <Box m="4" p="5">
    Same spacing on mobile, tablet, desktop, widescreen, and fullhd
  </Box>
</>
```

### Display Properties

```tsx live
<>
  Hide on mobile, show on desktop
  <Box visibility="hidden" viewport="mobile">
    Hidden on mobile
  </Box>

  Flex layout only on tablet+
  <Box display="flex" viewport="tablet" justifyContent="space-between">
    Flex layout on tablet+
    Space between items
  </Box>
</>
```

### Typography

Text size and alignment have dedicated per-viewport props — combine a base value with any `*Mobile` / `*Tablet` / `*Desktop` / `*Widescreen` / `*Fullhd` override.

```tsx live
<>
  Responsive text sizes
  <Title textSize="6" textSizeDesktop="3">
    Grows on desktop
  </Title>

  <Box textAlign="centered" textAlignDesktop="left">
    Centered on mobile/tablet, left-aligned on desktop
  </Box>
</>
```

## Column System Responsiveness

The column system is highly responsive with size controls per breakpoint:

### Basic Responsive Columns

```tsx live
<Columns>
  <Column
    size="full" // Full width on mobile
    sizeTablet="half" // Half width on tablet
    sizeDesktop="one-third" // One third on desktop
  >
    <Notification color="primary">Responsive column</Notification>
  </Column>
  <Column size="full" sizeTablet="half" sizeDesktop="two-thirds">
    <Notification color="info">Complementary column</Notification>
  </Column>
</Columns>
```

### Column Offsets

```tsx live
<Columns>
  <Column
    size="half"
    offset="one-quarter" // Offset on all sizes
    offsetTablet="0" // No offset on tablet+
  >
    <Notification color="warning">Responsive offset column</Notification>
  </Column>
</Columns>
```

### Narrow Columns

```tsx live
<Columns>
  <Column
    isNarrow // Content-sized on all
    isNarrowTablet={false} // Full-width on tablet
  >
    <Notification color="success">Conditionally narrow</Notification>
  </Column>
  <Column>
    <Notification color="danger">Flexible column</Notification>
  </Column>
</Columns>
```

## Grid System Responsiveness

The CSS Grid system provides modern responsive layout:

### Responsive Column Counts

```tsx live
<Grid
  isFixed
  fixedCols={2} // 2 columns by default
  fixedColsTablet={3} // 3 columns on tablet
  fixedColsDesktop={4} // 4 columns on desktop
  fixedColsWidescreen={5} // 5 columns on widescreen
  fixedColsFullhd={6} // 6 columns on fullhd
>
  {[...Array(12)].map((_, i) => (
    <Cell key={i}>
      <Notification>Cell {i + 1}</Notification>
    </Cell>
  ))}
</Grid>
```

### Smart Grid with Minimum Columns

```tsx live
<>
  Automatically responsive based on min column width
  <Grid minCol={4}>
    {[...Array(20)].map((_, i) => (
      <Cell key={i}>
        <Notification>{i + 1}</Notification>
      </Cell>
    ))}
  </Grid>
</>
```

## Best Practices

### Mobile-First Approach

Always design for mobile first, then enhance for larger screens:

```tsx live
<>
  Good: Mobile-first responsive design
  <Box
    p="3"
    textAlign="centered" // Centered on mobile
    textAlignDesktop="left" // Left-aligned on desktop
  >
    <Title
      textSize="5" // Smaller on mobile
      textSizeDesktop="3" // Larger on desktop
    >
      Responsive Title
    </Title>
    <Button size="small">Small Button</Button>
  </Box>
</>
```

### Test Across Breakpoints

Always test your layouts across all breakpoints.

Use browser dev tools to test these breakpoints:

- 375px (mobile)
- 768px (tablet boundary)
- 1024px (desktop boundary)
- 1216px (widescreen boundary)
- 1408px (fullhd boundary)

### Combine Techniques

Combine different responsive approaches for complex layouts:

```tsx live
<Container breakpoint="desktop" isMax>
  <Columns isMobile>
    <Column isNarrow isNarrowTablet={false} display="flex">
      <Box p="3" textAlign="centered" textAlignTablet="left">
        <Title textSize="5" textSizeTablet="4">
          Sidebar
        </Title>
      </Box>
    </Column>
    <Column>
      <Grid gap={2}>
        {[...Array(9)].map((_, i) => (
          <Cell key={i}>
            <Notification>Card {i + 1}</Notification>
          </Cell>
        ))}
      </Grid>
    </Column>
  </Columns>
</Container>
```

This creates a sophisticated responsive layout that adapts elegantly across all screen sizes while maintaining usability and visual hierarchy.

---

## Sass Customization


Sass customization is the **build-time half** of bestax's two-layer theming story. You set [Bulma's Sass variables](https://bulma.io/documentation/customize/with-sass/) once at build time to bake in defaults (brand colors, fonts, radii); then bestax's [`Theme` component](./css-variables.md) lets you adjust any of them at runtime via CSS variables. The two layers are designed to work together — Sass defines what ships, `Theme` adjusts what renders.

:::info Bulma's canonical reference
The authoritative documentation for customizing Bulma with Sass lives on the Bulma site:

- [Customize with Sass](https://bulma.io/documentation/customize/with-sass/) — end-to-end walkthrough of overriding Sass variables.
- [List of Sass variables](https://bulma.io/documentation/customize/list-of-sass-variables/) — the full catalog of initial, derived, and component-level variables.
- [Concepts](https://bulma.io/documentation/customize/concepts/) — how Sass variables flow into the generated CSS and CSS custom properties.
- [Customize with Modular Sass](https://bulma.io/documentation/customize/with-modular-sass/) — importing only the parts of Bulma you need.

This page focuses on wiring a Bulma Sass build into a bestax React project; refer to Bulma's docs for the variable reference and Sass semantics.
:::

:::tip Do you actually need a custom Sass build?
If you came in through `pnpm create bestax@latest`, you already picked one of the prebuilt Bulma flavors shipped with this library (`bestax-prefixed`, `bestax-no-helpers`, `bestax-no-dark-mode`, etc. — see `bulma-ui/src/scss/versions/`). Those are [modular Sass builds](https://bulma.io/documentation/customize/with-modular-sass/) of Bulma. That, plus runtime overrides through `Theme`, covers most projects. Reach for a custom Sass build when you need design tokens (brand colors, typography, control sizes) baked into the CSS that ships to users.
:::

## Overview

Sass variables feed the generated Bulma CSS — including the values of Bulma's CSS custom properties. Customize them at build time to set the **defaults** of your design system; then use the `Theme` component (or raw CSS variables) to override those defaults at runtime.

## Dependencies

To customize Bulma with Sass variables, you need:

```bash
pnpm add sass
pnpm add bulma
```

## Build Configuration

### Vite

Vite is the default toolchain for projects scaffolded by `pnpm create bestax@latest`, and handles Sass out of the box once `sass` is installed:

```bash
pnpm add sass
```

**`src/styles/bulma-custom.scss`:**

```scss
@use 'bulma/sass' with (
  $primary: #e91e63,
  $family-primary: '"Roboto", sans-serif',
  $radius-large: 12px,
  $control-height: 3rem
);
```

**Import directly in your entry:**

```tsx
// src/main.tsx

function App() {
  return (
    <Container>
      <Button color="primary">Vite + Sass Button</Button>
    </Container>
  );
}
```

### Next.js

Next.js has built-in Sass support:

**Install Sass:**

```bash
pnpm add sass
```

**Custom Sass file (styles/bulma-custom.scss):**

```scss
@use 'bulma/sass' with (
  $primary: #0070f3,
  $family-primary: '"Inter", sans-serif',
  $navbar-height: 4rem,
  $footer-padding: 3rem 1.5rem
);
```

**Import in \_app.tsx:**

```tsx
// pages/_app.tsx

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}
```

**Use in pages:**

```tsx
// pages/index.tsx

export default function Home() {
  return (
    <Hero size="medium">
      <Hero.Body>
        <Container>
          <Title>Next.js + Sass Customization</Title>
          <Button color="primary" size="large">
            Get Started
          </Button>
        </Container>
      </Hero.Body>
    </Hero>
  );
}
```

### Webpack / Create React App

Create React App is no longer actively developed — new projects should prefer Vite or Next.js. If you're maintaining an existing CRA app, you can compile a custom Sass file with a standalone `sass` CLI script and import the generated CSS:

```json
{
  "scripts": {
    "build-bulma": "sass --load-path=node_modules src/styles/bulma-custom.scss src/styles/bulma-custom.css",
    "watch-bulma": "pnpm build-bulma -- --watch"
  }
}
```

```tsx

```

## Common Sass Variables

The snippets below show the variables most projects customize. For the full catalog — initial, derived, and component-level — refer to Bulma's [List of Sass variables](https://bulma.io/documentation/customize/list-of-sass-variables/).

### Color Variables

```scss
@use 'bulma/sass' with (
  // Primary colors
  $primary: #3273dc,
  $link: #3273dc,
  $info: #3298dc,
  $success: #48c774,
  $warning: #ffdd57,
  $danger: #f14668,

  // Neutral colors
  $white: #ffffff,
  $black: #0a0a0a,
  $light: #f5f5f5,
  $dark: #363636,

  // Grey shades
  $grey-darker: #121212,
  $grey-dark: #363636,
  $grey: #4a4a4a,
  $grey-light: #b5b5b5,
  $grey-lighter: #dbdbdb
);
```

### Typography Variables

```scss
@use 'bulma/sass' with (
  // Font families
  $family-sans-serif: '"Inter", "SF Pro Display", sans-serif',
  $family-monospace: '"Fira Code", "SF Mono", monospace',
  $family-primary: $family-sans-serif,
  $family-secondary: $family-sans-serif,
  $family-code: $family-monospace,

  // Font sizes
  $size-1: 3rem,
  $size-2: 2.5rem,
  $size-3: 2rem,
  $size-4: 1.5rem,
  $size-5: 1.25rem,
  $size-6: 1rem,
  $size-7: 0.875rem,

  // Font weights
  $weight-light: 300,
  $weight-normal: 400,
  $weight-medium: 500,
  $weight-semibold: 600,
  $weight-bold: 700
);
```

### Layout Variables

```scss
@use 'bulma/sass' with (
  // Spacing
  $block-spacing: 1.5rem,
  $column-gap: 0.75rem,

  // Border radius
  $radius-small: 2px,
  $radius: 4px,
  $radius-medium: 6px,
  $radius-large: 8px,
  $radius-rounded: 9999px,

  // Control elements
  $control-height: 2.5em,
  $control-line-height: 1.5,
  $control-padding-vertical: calc(0.5em - 1px),
  $control-padding-horizontal: calc(0.75em - 1px)
);
```

### Component Variables

```scss
@use 'bulma/sass' with (
  // Button
  $button-padding-vertical: 0.5rem,
  $button-padding-horizontal: 1rem,
  $button-border-radius: $radius,

  // Input
  $input-shadow: inset 0 0.0625em 0.125em rgba(10, 10, 10, 0.05),
  $input-hover-border-color: $grey-dark,
  $input-focus-border-color: $link,

  // Card
  $card-shadow: 0 0.5em 1em -0.125em rgba(10, 10, 10, 0.1),
  $card-radius: $radius-large,

  // Navbar
  $navbar-height: 3.25rem,
  $navbar-padding-vertical: 1rem,
  $navbar-padding-horizontal: 2rem
);
```

## How Sass Feeds Bulma's CSS Variables

In Bulma v1, the values you pass to `@use 'bulma/sass'` are compiled into the defaults of the CSS custom properties Bulma exposes — see Bulma's [Concepts](https://bulma.io/documentation/customize/concepts/) page for the end-to-end flow from Sass variable to generated CSS variable:

```scss
@use 'bulma/sass' with (
  $primary: #ff6b35,
  $family-primary: '"Helvetica Neue", sans-serif'
);
```

```css
:root {
  --bulma-primary-h: 18deg;
  --bulma-primary-s: 100%;
  --bulma-primary-l: 60%;
  --bulma-family-primary: '"Helvetica Neue", sans-serif';
}
```

Those same CSS variables can be re-addressed at runtime through bestax's [`Theme` component](./css-variables.md) — so Sass sets the baseline, `Theme` overrides as needed.

## Integration with React Components

### Build-time Theme

```scss
// styles/corporate-theme.scss
@use 'bulma/sass' with (
  $primary: #1e3a8a,
  // Corporate blue
  $success: #059669,
  // Corporate green
  $family-primary: '"Open Sans", sans-serif',
  $radius: 2px,
  // Sharp corners
  $control-height: 3rem // Larger controls
);
```

```tsx
// App.tsx

function CorporateApp() {
  return (
    <Container>
      <Card>
        <Card.Content>
          <Title>Corporate Design System</Title>
          <Button color="primary">Corporate Button</Button>
          <Button color="success" ml="2">
            Action Button
          </Button>
        </Card.Content>
      </Card>
    </Container>
  );
}
```

### Combining with CSS Variables

You can use both approaches together - Sass for base configuration and CSS variables for runtime theming:

```scss
// Base theme with Sass
@use 'bulma/sass' with (
  $family-primary: '"Inter", sans-serif',
  $radius: 6px,
  $control-height: 2.75rem
);
```

```tsx
// Runtime theming with CSS variables

function App() {
  return (
    <Theme primaryH="270" primaryS="100%" primaryL="50%" isRoot>
      <CorporateApp />
    </Theme>
  );
}
```

## Best Practices

### 1. Establish Design Tokens

Define your design system values clearly:

```scss
// design-tokens.scss
$brand-blue: #1e40af;
$brand-green: #059669;
$brand-orange: #ea580c;

$font-primary: '"Inter", sans-serif';
$font-mono: '"JetBrains Mono", monospace';

$spacing-unit: 0.25rem;
$border-radius-base: 6px;

@use 'bulma/sass' with (
  $primary: $brand-blue,
  $success: $brand-green,
  $warning: $brand-orange,
  $family-primary: $font-primary,
  $family-code: $font-mono,
  $radius: $border-radius-base
);
```

### 2. Modular Sass Files

Organize your customizations by feature:

```scss
// styles/main.scss
@use './variables' as vars;
@use './typography';
@use './components';

@use 'bulma/sass' with (
  $primary: vars.$brand-primary,
  $family-primary: vars.$font-family-base
);
```

### 3. Environment-specific Builds

Create different themes for different environments:

```scss
// themes/development.scss
@use 'bulma/sass' with (
  $primary: #ef4444,
  // Red for development
  $warning: #f59e0b
);

// themes/production.scss
@use 'bulma/sass' with (
  $primary: #3b82f6,
  // Blue for production
  $warning: #f59e0b
);
```

## Pairing Sass Defaults with Runtime Overrides

A typical bestax project uses both layers together: Sass sets shipped defaults, `Theme` adjusts them per-context or per-user.

```scss
@use 'bulma/sass' with (
  $primary: #8b5cf6,
  $radius: 8px
);
```

```tsx
<Theme
  primaryH="258"
  primaryS="90%"
  primaryL="64%"
  bulmaVars={{ '--bulma-radius': '12px' }}
>
  <App />
</Theme>
```

## Further Reading

- [CSS Variables (bestax guide)](./css-variables.md) — the runtime half of the theming story.
- [Theme component reference](../../api/helpers/theme.md) — the full bestax React API.
- [Bulma: Customize with Sass](https://bulma.io/documentation/customize/with-sass/) — Bulma's official Sass customization guide.
- [Bulma: List of Sass variables](https://bulma.io/documentation/customize/list-of-sass-variables/) — the complete variable catalog.
- [Bulma: Customize with Modular Sass](https://bulma.io/documentation/customize/with-modular-sass/) — importing only the parts of Bulma you need.
- [Bulma: Concepts](https://bulma.io/documentation/customize/concepts/) — how Sass variables feed Bulma's CSS custom properties.

---

## Icons


bestax-bulma supports five icon libraries out of the box: **Font Awesome**, **Material Design Icons**, **Ionicons**, **Google Material Icons**, and **Material Symbols**. Font Awesome is the default when no `library` prop is set.

:::tip Easiest path: `create-bestax`
The [Quick Start](/docs/guides/intro) installer prompts you to pick an icon library (or none) and handles the install, CSS import, and any needed `ConfigProvider` wiring automatically. Use the manual steps below if you're adding icons to an existing project or want to switch libraries later.
:::

---

## Font Awesome

Font Awesome is the default icon library — no `library` prop required.

**Install:**

```bash
pnpm add @fortawesome/fontawesome-free
```

**Import:**

Add this to your main application file (e.g., `main.tsx` or `App.tsx`):

```js

```

**Usage:**

```tsx live

function FontAwesomeExample() {
  return (
    <Button color="primary">
      <Icon name="user" />
      Profile
    </Button>
  );
}
```

**Variants** (Font Awesome styles):

- Solid (default): `<Icon name="user" />`
- Regular: `<Icon name="user" variant="regular" />`
- Brands: `<Icon name="github" variant="brands" />`
- Light, Duotone, and Thin are also available via the `variant` prop.

:::info Library values
The `library` prop defaults to `"fa"` (Font Awesome). You only need to set it when using another library, e.g., `library="mdi"`.
:::

---

## Material Design Icons

Material Design Icons (MDI) is a comprehensive icon library that follows Google's Material Design guidelines.

**Install:**

```bash
pnpm add @mdi/font
```

**Import:**

Add this to your main application file (e.g., `main.tsx` or `App.tsx`):

```js

```

**Usage:**

```tsx live

function MaterialIconExample() {
  return (
    <Button color="primary">
      <Icon library="mdi" name="home" />
      Home
    </Button>
  );
}
```

---

## Ionicons

Ionicons is a modern icon library with 1,300+ icons designed specifically for web, iOS, Android, and desktop apps. The library now uses web components for better performance and loading.

**Install:**

```bash
pnpm add ionicons@^8.0.13
```

**Import:**

:::info No CSS Import Needed

Ionicons v8 uses web components that are automatically loaded in your documentation examples.

:::

**Setup for Your Application:**

For your own application, you need to import the ionicons ES module. Add this to your main application file (e.g., `index.js`, `App.js`, or `main.tsx`):

```js
// Import ionicons as ES module - this will auto-register the web components

```

**Alternative Setup (CDN):**

You can also load ionicons via CDN by adding these script tags to your HTML:

```html
<script
  type="module"
  src="https://unpkg.com/ionicons@8.0.13/dist/ionicons/ionicons.esm.js"
></script>
<script
  nomodule
  src="https://unpkg.com/ionicons@8.0.13/dist/ionicons/ionicons.js"
></script>
```

**Usage:**

```tsx live

function IoniconExample() {
  return (
    <Button color="info">
      <Icon library="ion" name="settings" />
      Settings
    </Button>
  );
}
```

**Available Icon Variants:**

Ionicons v8 provides three variants for most icons:

```tsx live

function IoniconVariants() {
  return (
    <Columns isVCentered>
      <Column isNarrow textAlign="center">
        <Icon library="ion" name="heart" />
        <Block fontSize="small" mt={1}>
          Default
        </Block>
      </Column>
      <Column isNarrow textAlign="center">
        <Icon library="ion" name="heart-outline" />
        <Block fontSize="small" mt={1}>
          Outline
        </Block>
      </Column>
      <Column isNarrow textAlign="center">
        <Icon library="ion" name="heart-sharp" />
        <Block fontSize="small" mt={1}>
          Sharp
        </Block>
      </Column>
    </Columns>
  );
}
```

:::info Ionicons v8 Web Components
Ionicons v8 uses modern web components instead of CSS fonts. This provides:

- **Better performance**: Only loads icons that are actually used
- **Smaller bundle size**: No need to include entire font files
- **SVG-based rendering**: Crisp icons at any size
- **Automatic loading**: Icons load dynamically as needed

Web components are automatically registered in documentation examples, so no additional setup is required.
:::

:::tip Icon Naming Convention
Ionicons v8 simplified the naming convention:

- **Default (filled)**: `heart`, `settings`, `home`
- **Outline**: `heart-outline`, `settings-outline`, `home-outline`
- **Sharp**: `heart-sharp`, `settings-sharp`, `home-sharp`

The old iOS/MD prefixes (`ios-heart`, `md-heart`) are no longer used in v8.

You can also pass the variant separately — `<Icon library="ion" name="heart" variant="outline" />` is equivalent to `<Icon library="ion" name="heart-outline" />`.
:::

---

## Google Material Icons

Google's official Material Icons library provides the core set of Material Design icons.

**Install:**

```bash
pnpm add material-icons
```

**Import:**

Add this to your main application file (e.g., `main.tsx` or `App.tsx`):

```js
// Default import (includes all styles)

// Or import the base CSS file

```

**SASS Import:**

```scss
@import 'material-icons/iconfont/material-icons.scss';
```

**Selective Imports (for smaller bundle size):**

```js
// Import only specific styles you need

```

**Usage:**

```tsx live

function GoogleMaterialIconExample() {
  return (
    <Button color="success">
      <Icon library="material-icons" name="home" />
      Home
    </Button>
  );
}
```

**Available Icon Styles:**

The Google Material Icons library includes different styles that can be used via `variant`:

```tsx live

function MaterialIconStyles() {
  return (
    <Columns isVCentered>
      <Column isNarrow>
        <Icon library="material-icons" name="account_circle" color="danger" />
      </Column>
      <Column isNarrow>
        <Icon
          library="material-icons"
          name="account_circle"
          variant="outlined"
          color="danger"
        />
      </Column>
      <Column isNarrow>
        <Icon
          library="material-icons"
          name="account_circle"
          variant="round"
          color="danger"
        />
      </Column>
      <Column isNarrow>
        <Icon
          library="material-icons"
          name="account_circle"
          variant="sharp"
          color="danger"
        />
      </Column>
    </Columns>
  );
}
```

:::tip Icon Styles

- **Default (Filled)**: Standard filled icons (default, no `variant` needed)
- **Outlined**: `variant="outlined"`
- **Round**: `variant="round"`
- **Sharp**: `variant="sharp"`
  :::

:::info Documentation
For a complete list of available icons and detailed usage instructions, visit the [material-icons package documentation](https://www.npmjs.com/package/material-icons).
:::

---

## Material Symbols

The newest icon library from Google, offering more comprehensive icon coverage and modern design.

**Install:**

```bash
pnpm add material-symbols
```

**Import:**

Add this to your main application file (e.g., `main.tsx` or `App.tsx`):

```js
// Default import (includes all styles)

```

**SASS Import:**

```scss
@import 'material-symbols';
```

**Selective Imports (for smaller bundle size):**

```js
// Import only specific styles you need

```

**Usage:**

```tsx live

function MaterialSymbolExample() {
  return (
    <Button color="warning">
      <Icon library="material-symbols" name="home" />
      Home
    </Button>
  );
}
```

**Available Symbol Styles:**

Material Symbols come in three styles. The default import includes all styles, but you can import selectively:

```tsx live

function MaterialSymbolStyles() {
  return (
    <>
      <Columns isVCentered>
        <Column size={2} textWeight="bold">
          Outlined:
        </Column>
        <Column isNarrow>
          <Icon
            library="material-symbols"
            name="delete"
            size="large"
            features="is-size-1"
          />
        </Column>
        <Column isNarrow>
          <Icon
            library="material-symbols"
            name="settings"
            size="large"
            features="is-size-1"
          />
        </Column>
        <Column isNarrow>
          <Icon
            library="material-symbols"
            name="grade"
            size="large"
            features="is-size-1"
          />
        </Column>
      </Columns>

      <Columns isVCentered>
        <Column size={2} textWeight="bold">
          Rounded:
        </Column>
        <Column isNarrow>
          <Icon
            library="material-symbols"
            name="delete"
            variant="rounded"
            size="large"
            features="is-size-1"
          />
        </Column>
        <Column isNarrow>
          <Icon
            library="material-symbols"
            name="settings"
            variant="rounded"
            size="large"
            features="is-size-1"
          />
        </Column>
        <Column isNarrow>
          <Icon
            library="material-symbols"
            name="grade"
            variant="rounded"
            size="large"
            features="is-size-1"
          />
        </Column>
      </Columns>

      <Columns isVCentered>
        <Column size={2} textWeight="bold">
          Sharp:
        </Column>
        <Column isNarrow>
          <Icon
            library="material-symbols"
            name="delete"
            variant="sharp"
            size="large"
            features="is-size-1"
          />
        </Column>
        <Column isNarrow>
          <Icon
            library="material-symbols"
            name="settings"
            variant="sharp"
            size="large"
            features="is-size-1"
          />
        </Column>
        <Column isNarrow>
          <Icon
            library="material-symbols"
            name="grade"
            variant="sharp"
            size="large"
            features="is-size-1"
          />
        </Column>
      </Columns>
    </>
  );
}
```

:::tip Symbol Styles

- **Outlined**: Default style (no `variant` needed)
- **Rounded**: `variant="rounded"`
- **Sharp**: `variant="sharp"`
  :::

:::info Material Symbols vs Material Icons
Material Symbols is Google's newer icon system with:

- More comprehensive icon coverage (2,500+ icons)
- Better optical sizing and variable font support
- Consistent design across all platforms
- Recommended for new projects

For a complete list of available symbols and detailed usage instructions, visit the [material-symbols package documentation](https://www.npmjs.com/package/material-symbols).
:::

---

:::tip Skip the manual setup
If you haven't started your project yet, `pnpm create bestax@latest` will install and wire up any of these icon libraries for you. See the [Quick Start](/docs/guides/intro).
:::

---

## Choosing the Right Icon Library

| Library                   | Icons Count | File Size | Best For                        |
| ------------------------- | ----------- | --------- | ------------------------------- |
| **Font Awesome**          | 2,000+      | ~75KB     | General purpose, most popular   |
| **Material Design Icons** | 7,000+      | ~50KB     | Material Design projects        |
| **Ionicons v8**           | 1,300+      | Dynamic   | Modern web components, mobile   |
| **Google Material Icons** | 1,100+      | ~45KB     | Official Google Material Design |
| **Material Symbols**      | 2,500+      | ~55KB     | Modern Material Design projects |

---

## Icon Name References

- **Font Awesome**: [fontawesome.com/icons](https://fontawesome.com/icons)
- **Material Design Icons**: [materialdesignicons.com](https://materialdesignicons.com/)
- **Ionicons v8**: [ionicons.com](https://ionicons.com/) • [NPM Package](https://www.npmjs.com/package/ionicons)
- **Google Material Icons**: [fonts.google.com/icons](https://fonts.google.com/icons?icon.set=Material+Icons) • [NPM Package](https://www.npmjs.com/package/material-icons)
- **Material Symbols**: [fonts.google.com/icons](https://fonts.google.com/icons?icon.set=Material+Symbols) • [NPM Package](https://www.npmjs.com/package/material-symbols)

---

## Next Steps

- **Learn about Icon component props**: [Icon API](/docs/api/elements/icon)
- **Explore IconText component**: [IconText API](/docs/api/elements/icontext)
- **Browse CSS variations**: [CSS Variations](/docs/guides/getting-started/variations)

---

## Contributing

# Contributing to bestax-bulma

Thanks for your interest in contributing! This page mirrors the highlights of the repository's
[`CONTRIBUTING.md`](https://github.com/allxsmith/bestax/blob/main/CONTRIBUTING.md) — which stays the
canonical source — and gives you a copy-pasteable **local development command reference** for the
pnpm toolchain.

## Requirements

Before opening a PR, make sure:

- **All tests pass** (`pnpm test` & `pnpm test:coverage`) — coverage must stay **≥ 95%**.
- **Lint, format, and type checks pass** (`pnpm lint`, `pnpm format:check`, `pnpm typecheck`).
- **Storybook covers UI changes** — any UI change needs a corresponding story.
- **Docs are updated** for new or changed behavior.
- **CI passes** (`pnpm all`) and the PR targets `main` (direct pushes to `main` aren't allowed).

## Prerequisites

Use **Node 22** (the LTS this repo targets — see [`.nvmrc`](https://github.com/allxsmith/bestax/blob/main/.nvmrc)).
The repo uses **pnpm**, pinned via the `packageManager` field. The simplest way to get the exact
version on any Node is to enable **Corepack** (bundled with Node):

```bash
corepack enable
```

pnpm powers the project's supply-chain hardening — lifecycle/postinstall scripts are blocked by
default and a 3-day release-age cooldown prevents installing just-published versions. See
[`pnpm-workspace.yaml`](https://github.com/allxsmith/bestax/blob/main/pnpm-workspace.yaml) for the
exact settings.

## Local Development Commands

Everything here is safe to run locally; **nothing publishes** (see the note at the end).

### 1. One-time setup

```bash
corepack enable                    # makes `pnpm` use the pinned pnpm@11.9.0
pnpm install --frozen-lockfile     # exact CI-parity install (fails if the lockfile drifts)
# or just `pnpm install` for a normal dev install
```

### 2. Run the whole CI suite locally (the big one)

```bash
pnpm run all
# = turbo: build, typecheck, test, test:coverage, bundle:stats, lint,
#   format:check  &&  build-storybook (bulma-ui)
```

### 3. Individual checks

```bash
pnpm run build          # turbo build all packages
pnpm run typecheck
pnpm run test           # jest (bulma-ui + create-bestax)
pnpm run test:coverage  # coverage (must stay >= 95%)
pnpm run lint
pnpm run format:check   # prettier check (use `pnpm run format` to auto-fix)
pnpm run bundle:stats   # writes bulma-ui/dist/stats.html
```

### 4. Docusaurus (docs site → http://localhost:3000)

```bash
pnpm docs                                                   # dev server (hot reload)

# production build + preview:
pnpm exec turbo run build --filter=@allxsmith/bestax-docs   # builds docs + bulma-ui dep
pnpm --filter @allxsmith/bestax-docs run serve              # serves the built site
```

The build also regenerates `/llms.txt` and `/llms-full.txt` under `docs/build/`.

### 5. Storybook (→ http://localhost:6006)

```bash
pnpm storybook                                              # dev server
pnpm --filter @allxsmith/bestax-bulma run build-storybook   # static build -> bulma-ui/storybook-static
```

### 6. Turbo directly (filters + caching)

```bash
pnpm exec turbo run build --filter=@allxsmith/bestax-bulma   # one package (+ its deps)
pnpm exec turbo run test --filter=create-bestax
pnpm exec turbo run build                                    # everything (cached on re-run)
pnpm exec turbo run build --force                            # ignore turbo cache
```

### 7. create-bestax — scaffold a throwaway app

Scaffold **outside the repo** so it's a standalone app (inside the repo you'd need
`--ignore-workspace`):

```bash
pnpm --filter create-bestax run build
node "$PWD/create-bestax/dist/index.js" /tmp/my-bestax-app -t vite-ts -b complete -i fontawesome -y
cd /tmp/my-bestax-app && pnpm install && pnpm dev     # verify the generated app runs
```

### 8. Supply-chain / pnpm hardening checks

```bash
pnpm audit --audit-level=high     # the CI gate (should exit 0)
pnpm approve-builds               # shows which install scripts are blocked/allowed
pnpm why serialize-javascript     # trace a transitive dep (confirms the >=7.0.3 override)
pnpm why prettier                 # confirm a single pinned version
pnpm outdated -r                  # what's behind (the cooldown may hold some back)
pnpm list --depth 0               # top-level deps per workspace
pnpm dedupe --check               # report duplicate versions without changing anything
```

Want to _see the cooldown block something_? Try adding a just-published package — pnpm refuses it
(then discard the change):

```bash
pnpm add -w some-brand-new-package         # expect ERR_PNPM_MINIMUM_RELEASE_AGE_VIOLATION
git checkout package.json pnpm-lock.yaml   # undo
```

### 9. Preview the release without publishing (semantic-release dry-run)

Runs the real commit analysis and next-version calc, but publishes nothing:

```bash
export GITHUB_TOKEN=your_token   # the github plugin needs a repo-read token even in dry-run
cd bulma-ui      && pnpm exec semantic-release --dry-run --no-ci ; cd ..
cd create-bestax && pnpm exec semantic-release --dry-run --no-ci ; cd ..
```

It prints "The next release version is X.Y.Z" per package (or "no release") from your local commits —
no `npm publish`, no tag, no GitHub release.

:::tip Safe to run; never publishes
Everything above is safe. The only things that actually publish are `pnpm exec semantic-release`
**without** `--dry-run` (CI-only, on merge to `main`) and a manual `npm publish` — neither of which
is in this list.
:::

## Workflow & conventions

1. Branch off `main`, make your change in the right workspace (`bulma-ui`, `create-bestax`, or `docs`).
2. Add/update tests (≥ 95% coverage) and Storybook stories for UI changes.
3. Run `pnpm all`, then open a PR targeting `main`.

Commits follow [Conventional Commits](https://www.conventionalcommits.org/) — the type and scope
drive [semantic-release](https://semantic-release.gitbook.io/). Releasing types (`feat`, `fix`,
`perf`, `refactor`, `style`) must be scoped to `bulma-ui` or `create-bestax`; `docs`, `chore`, `ci`,
`build`, and `test` don't publish. Publishing uses npm **OIDC trusted publishing** with **provenance**
(no long-lived token). See [`CONTRIBUTING.md`](https://github.com/allxsmith/bestax/blob/main/CONTRIBUTING.md)
for the full details.

---

## Installation

# Installation Guide

This comprehensive guide covers all installation options, prerequisites, and configuration choices for bestax-bulma.

:::tip Quick Setup
Most users should run `pnpm create bestax@latest` — it handles everything on this page automatically (CSS imports, icon fonts, TypeScript) and offers to preinstall the [bestax AI skills](/docs/skills/intro) into `.claude/skills/`. See the [Quick Start](/docs/guides/intro) for the 2-minute flow. This guide is for manual setup.
:::

:::info Already Configured?
If you've already installed everything and want to start building, explore our [Component Documentation](/docs/category/elements) to see live examples, props, and usage patterns for all bestax-bulma components.
:::

---

## Prerequisites

### System Requirements

- **Node.js**: 22.0.0 or higher (the current LTS baseline)
- **npm**: 10.0.0 or higher (ships with Node 22; or yarn/pnpm)
- **React**: 18.0.0 or higher (React 18 or 19; v4 dropped React 16/17 support)

### HTML Setup

Ensure your HTML document includes the viewport meta tag for responsive design:

```html
<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Your App</title>
  </head>
  <body>
    
  </body>
</html>
```

:::warning Important
The viewport meta tag is **essential** for Bulma's responsive features. Without it, mobile layouts won't work correctly.
:::

---

## Package Installation

:::info Prefer the installer
`pnpm create bestax@latest` installs the package, wires up the CSS, and scaffolds a working app in one step. Only follow the manual steps below if you're adding bestax-bulma to an existing project or using a toolchain the installer doesn't cover.
:::

### Using npm (recommended)

```bash
pnpm add @allxsmith/bestax-bulma
```

### Using yarn

```bash
yarn add @allxsmith/bestax-bulma
```

### Using pnpm

```bash
pnpm add @allxsmith/bestax-bulma
```

### Version Management

To see available versions:

```bash
npm view @allxsmith/bestax-bulma versions
```

To install a specific version, append `@<version>` to the package name (e.g. `pnpm add @allxsmith/bestax-bulma@<version>`).

---

## Bulma CSS Setup

Bulma CSS is included automatically when you install bestax-bulma. For most users, Method 1 is all you need:

### Method 1: Combined Bundle (Recommended)

The simplest approach — a single import that includes both Bulma and all bestax extras:

```js

```

This is all you need. No separate Bulma CSS import required.

### Method 2: Separate Imports

If you prefer to import Bulma CSS separately (e.g., for a specific Bulma variant), you'll need both Bulma and the bestax extras:

```js

```

Bulma is already installed as a dependency of bestax-bulma — no extra install needed.

### Method 3: CDN

**Pros**: Quick setup, no build step required, always latest version
**Cons**: Requires internet connection, no tree shaking

Add to your HTML `<head>`:

```html
<!-- Bestax combined bundle (Bulma + extras) -->
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/@allxsmith/bestax-bulma/dist/bestax.css"
/>
```

Or if you only need Bulma itself:

```html
<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/bulma@1.0.4/css/bulma.min.css"
/>
```

### Method 4: Custom SCSS Build

**Pros**: Smallest bundle size, full customization
**Cons**: More complex setup

1. Install Sass as a dev dependency (Bulma is already installed):

```bash
pnpm add -D sass
```

2. Create a custom SCSS file:

```scss
// custom-bestax.scss
@use 'bulma/sass' with (
  $primary: #00d1b2,
  $link: #3273dc
);

// Include bestax extras
@use '@allxsmith/bestax-bulma/scss/extras';
```

3. Import your custom build:

```js

```

---

## Icon Libraries

bestax-bulma components support multiple icon libraries. Icons are optional but enhance the user experience.

:::tip
`create-bestax` installs and wires up any of these for you when you pick one at the prompt. The steps below are for setting up an icon library by hand.
:::

### Font Awesome (Most Popular)

```bash
pnpm add @fortawesome/fontawesome-free
```

Import in your main file:

```js

```

Usage: `<Icon name="user" />` or `<Icon name="github" variant="brands" />`

### Material Design Icons

```bash
pnpm add @mdi/font
```

```js

```

Usage: `<Icon name="account" library="mdi" />`

### Material Icons (Google)

```bash
pnpm add material-icons
```

```js

```

Usage: `<Icon name="person" library="material-icons" />`

### Ionicons

```bash
pnpm add ionicons
```

```js

```

Usage: `<Icon name="person" library="ion" />`

---

## CSS Import Order

The order of CSS imports matters for proper styling precedence:

```js
// 1. First: Bestax CSS (Bulma + extras combined)

// 2. Second: Icon libraries (if using)

// 3. Third: Any theme or override CSS

// 4. Last: Your custom styles

```

If using separate imports instead:

```js
// 1. First: Bulma CSS

// 2. Second: Extras CSS

// 3. Third: Icon libraries (if using)

// 4. Last: Your custom styles

```

:::caution Style Conflicts
If Bulma styles are being overridden unexpectedly, check your CSS import order. Bulma should be imported before your custom styles.
:::

---

## TypeScript Setup

bestax-bulma includes TypeScript definitions. For the best experience:

### Install Type Definitions

```bash
pnpm add -D typescript @types/react @types/react-dom
```

### TypeScript Configuration

Recommended `tsconfig.json` settings:

```json
{
  "compilerOptions": {
    "target": "ES2020",
    "useDefineForClassFields": true,
    "lib": ["ES2020", "DOM", "DOM.Iterable"],
    "module": "ESNext",
    "skipLibCheck": true,
    "moduleResolution": "node",
    "allowSyntheticDefaultImports": true,
    "esModuleInterop": true,
    "jsx": "react-jsx",
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  }
}
```

---

## Bundle Size Optimization

Optional tuning once you have bestax-bulma installed and rendering.

### Tree Shaking

bestax-bulma supports tree shaking. Always use named imports:

```js
// ✅ Good - Only imports what you need

// ❌ Bad - Imports entire library

```

### Analyzing Bundle Size

To analyze your bundle:

1. Install bundle analyzer:

```bash
pnpm add -D webpack-bundle-analyzer
```

2. Check what's included:

```bash
pnpm dlx webpack-bundle-analyzer stats.json
```

### Expected Sizes

- **bestax-bulma**: ~40KB (gzipped)
- **Bulma CSS**: ~30KB (gzipped)
- **With PurgeCSS**: Can reduce Bulma CSS further

---

## Environment-Specific Setup

Notes for specific environments, only relevant after the core install above is working.

### Development & Production

`bestax.css` is already compressed, so the same import works for both environments:

```js

```

For production builds, consider enabling CSS purging (remove unused styles) or using a CDN for better caching.

### Testing

For testing environments:

```js
// jest.setup.js

// Mock CSS imports
jest.mock('@allxsmith/bestax-bulma/bestax.css', () => ({}));
```

---

## Verification

After installation, verify everything is working:

### 1. Check Package Installation

```bash
npm list @allxsmith/bestax-bulma
```

### 2. Check Import Resolution

Your IDE should autocomplete:

```js

```

### 3. Check Styling

Components should have Bulma styling applied. If components appear unstyled:

- Verify bestax CSS is imported
- Check browser console for 404 errors
- Ensure CSS import order is correct

### 4. Check Icons (if using)

Icons should render correctly. If you see placeholder text instead of icons:

- Verify icon library CSS is imported
- Check the icon name matches the library's naming convention

---

## Troubleshooting

### Common Issues

**Components are unstyled**

- Solution: Ensure bestax CSS is imported in your main file

**Icons not showing**

- Solution: Import the icon library CSS and verify icon names

**TypeScript errors**

- Solution: Install `@types/react` and `@types/react-dom`

**Large bundle size**

- Solution: Use named imports and consider CSS purging

**Mobile layout broken**

- Solution: Add viewport meta tag to your HTML

### Getting Help

- Check our [Toolchains guide](/docs/guides/getting-started/react-setups) for toolchain-specific issues
- View [example projects](https://github.com/allxsmith/bestax/tree/main/examples)
- Open an [issue on GitHub](https://github.com/allxsmith/bestax/issues)

---

## Next Steps

Now that you understand the installation options:

1. **Choose your toolchain** → [Toolchains Guide](/docs/guides/getting-started/react-setups)
2. **Explore components** → [Component Documentation](/docs/category/elements)
3. **Customize styling** → [Theming Guide](/docs/api/helpers/theme)
4. **Configure globally** → [Config Provider](/docs/api/helpers/config)

---

## Bulma 0.9.4 → 1.x

# Migrating from Bulma v0.9.x → Bulma v1

bestax-bulma has always required Bulma v1, so upgrading bestax itself never requires a Bulma migration. This page is here for two situations where the Bulma upgrade is relevant alongside (or before) adopting bestax:

- You're **migrating off another React + Bulma library** (e.g. `react-bulma-components`, Buefy, an in-house wrapper) that was pinned to Bulma 0.9.x.
- You have **plain Bulma 0.9.x in your project** today (separate stylesheets, custom Sass) and you want to upgrade Bulma itself so you can adopt bestax cleanly.

Either way, the changes you'll see at the Bulma layer are the same — captured below.

## Easy HTML compatibility

:::tip HTML stays the same
All Bulma v0.9.x HTML snippets remain valid in v1. You don't need to update markup or React component output — only your CSS / Sass build.
:::

You can keep your existing components, classes, and JSX as-is.

You can simply update your CSS import from:

```js
// Old: Bulma v0.9.4

```

To:

```js
// New: Bulma v1.0.0+

```

Your components will continue to work. Things may look slightly different due to design improvements, but functionality remains intact.

## Sass compiler change

Bulma v1 uses **Dart Sass** instead of the deprecated Node Sass:

- If you use the `sass` npm package, you're already using Dart Sass.
- The old `node-sass` package is no longer supported.
- Build times may be faster with Dart Sass.

```bash
# Remove old dependency
npm uninstall node-sass

# Install modern Sass compiler
pnpm add sass
```

## CSS variables support

One of the biggest changes in Bulma v1 is **CSS custom properties (variables)** instead of static values:

```css
/* Old: Static values */
color: hsl(171deg, 100%, 41%);

/* New: CSS variables */
color: var(--bulma-primary);
```

This means you can customize Bulma at **runtime** without needing Sass compilation:

```css
:root {
  --bulma-primary-h: 270deg;
  --bulma-primary-s: 100%;
  --bulma-primary-l: 50%;
}
```

## New features in Bulma v1

### Themes

Bulma v1 introduces **themes** — collections of CSS variables that can be applied to different contexts. bestax-bulma exposes a `<Theme>` component for this:

```tsx live
<Theme primaryH="270" primaryS="100%" primaryL="50%">
  <Box p="4">
    <Button color="primary">Purple themed button</Button>
  </Box>
</Theme>
```

Learn more in our [Theme documentation](../../../api/helpers/theme.md).

### Dark mode

```tsx live
<Theme bulmaVars={{ '--bulma-scheme-invert-ter': 'var(--bulma-scheme-main)' }}>
  <Card>
    <Box p="5">
      <Title>Dark mode content</Title>
    </Box>
  </Card>
</Theme>
```

### Color palettes

Each of the 7 primary colors now has a complete palette with shades:

```tsx live
<Buttons>
  <Button color="primary" colorShade="10">
    Primary Light
  </Button>
  <Button color="primary" colorShade="30">
    Primary Medium
  </Button>
  <Button color="primary" colorShade="60">
    Primary Dark
  </Button>
  <Button color="primary" colorShade="90">
    Primary Darker
  </Button>
</Buttons>
```

### Skeleton loaders

```tsx live
<Card>
  <Box p="4">
    <Title skeleton>Loading title…</Title>
    <Button skeleton>Loading button</Button>
    <Icon name="star" skeleton ariaLabel="Loading icon" />
  </Box>
</Card>
```

### CSS Grid support

Bulma v1 introduces true CSS Grid (not flexbox-based "grids"):

```tsx live
<Grid minCol={3} gap={2}>
  {[...Array(9)].map((_, i) => (
    <Cell key={i}>
      <Notification color="primary">Cell {i + 1}</Notification>
    </Cell>
  ))}
</Grid>
```

Learn more in our [Grid documentation](../../../api/grid/grid.md).

## Deprecated in Bulma v1

### Tiles → Grid

:::caution Tiles are deprecated
The Tile system is deprecated in Bulma v1. Migrate to the new CSS Grid system below — it's more powerful and uses real CSS Grid under the hood.
:::

❌ Old (deprecated):

```tsx

  
    Content
  

```

✅ New:

```tsx live
<Grid isFixed fixedCols={3}>
  <Cell>
    <Box>Content</Box>
  </Cell>
</Grid>
```

The new Grid system is more powerful and flexible.

## Runtime customization

Unlike Bulma v0.9.x, which required Sass compilation for customization, v1 allows runtime tweaks via CSS variables:

```css
/* Change primary color in DevTools */
:root {
  --bulma-primary-h: 120deg; /* Green instead of teal */
}
```

Or programmatically with the `<Theme>` component:

```tsx live
function example() {
  const [isDark, setIsDark] = useState(false);
  return (
    <Theme
      schemeH={isDark ? '220' : '0'}
      lightL={isDark ? '15%' : '96%'}
      darkL={isDark ? '85%' : '4%'}
    >
      <Container>
        <Button onClick={() => setIsDark(!isDark)}>
          Toggle {isDark ? 'Light' : 'Dark'} Mode
        </Button>
      </Container>
    </Theme>
  );
}
```

## Sass to CSS variables

If you were customizing Bulma with Sass variables:

```scss
// Old: Sass customization (v0.9.x)
$primary: #ff6b35;
$family-primary: 'Helvetica Neue', sans-serif;

@import 'bulma/bulma.sass';
```

Consider migrating to CSS variables for runtime flexibility:

```tsx
// New: Runtime customization (v1.x)
<Theme
  isRoot
  primaryH="18"
  primaryS="100%"
  primaryL="60%"
  bulmaVars={{
    '--bulma-family-primary': '"Helvetica Neue", sans-serif',
  }}
>
  <App />
</Theme>
```

## Best practices

1. **Start with CSS** — update to Bulma v1 CSS first to ensure compatibility.
2. **Test thoroughly** — verify all components render correctly.
3. **Add new features** — gradually introduce themes, CSS variables, and new components.
4. **Optimize later** — move to modular imports for better bundle size.

## Migration tool

:::info Coming soon
The migration tool described below is in development and not yet published. The command will eventually be `pnpm dlx bestax-bulma-migrate`. In the meantime, the manual steps in this guide cover the same ground.
:::

We're developing a migration tool to help you transition from older React Bulma libraries to bestax-bulma:

```bash
# Coming soon: Automated migration tool
pnpm dlx bestax-bulma-migrate
```

This tool will use jscodeshift to:

- Update imports from older React Bulma packages.
- Migrate from Bulma v0.9.4 class patterns to v1.x.
- Convert deprecated Tile usage to Grid components.
- Update theme and configuration patterns.

### Request migration support

If you're using a specific React Bulma package that isn't supported by our migration tool yet, please [open a feature request](https://github.com/allxsmith/bestax/issues/new?template=feature-request.md) and tell us:

- Which React Bulma package you're currently using.
- What components or patterns you need help migrating.
- Any specific challenges you're facing.

This helps us prioritize which packages to support next.

---

## bestax-bulma 2.x → 3.x

# Upgrading bestax-bulma 2.x → 3.x

This guide explains what changes when you upgrade `@allxsmith/bestax-bulma` from 2.x to 3.x. Most of your code keeps working unchanged. The areas that need attention are called out below.

## TL;DR

:::tip Mostly additive
3.x ships about 30 new components and several quality-of-life prop additions. The two changes that need active attention are **form input auto-wrapping** (Input/Select/TextArea/File) and **themed Radio/Checkbox** which now require the new extras CSS. Everything else is backward compatible or opt-in.
:::

| Area                     | What changed                                                                               | Action                                                                       |
| ------------------------ | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| Form inputs              | `<Input>`, `<Select>`, `<TextArea>`, `<File>` auto-wrap in `<Field><Control>`              | Use `InputBase` / `SelectBase` / `TextAreaBase` if you need the bare element |
| `<Radio>` / `<Checkbox>` | Custom-styled with hidden native input — **requires the new extras CSS to render visibly** | Import `@allxsmith/bestax-bulma/dist/extras.css` (or `bestax.css`)           |
| `<Tabs>`                 | New context + opt-in `<Tabs.Tab>` API                                                      | None — old `<Tabs.Item>` is preserved                                        |
| `<Field>`                | `labelSize` defaults to `'normal'` for horizontal layouts                                  | None unless you customised label baseline alignment                          |
| `<Checkboxes>`           | Now an optional state container (additive)                                                 | None — pass `value`/`onChange` only if you want group state                  |
| `<Radios>`               | Now an optional state container (additive)                                                 | None — pass `value`/`onChange` only if you want group state                  |
| `<Notification>`         | New programmatic singleton API (additive)                                                  | None — JSX usage unchanged                                                   |
| Subcomponent prop API    | Many subcomponents now extend `HTMLAttributes` (superset)                                  | None                                                                         |
| `bulma` package          | Moved from `peerDependencies` to `dependencies`                                            | Optional cleanup of your own peerDeps                                        |

## Form components: auto-wrap in Field & Control

:::caution The one breaking change
This is the only behavioral change in 3.x that can affect existing code without you opting in. If you only read one section of this guide, read this one.
:::

In 2.x, the form input components rendered the bare HTML element with Bulma classes:

```jsx
<Input value="hi" />
// → <input class="input" value="hi" />
```

In 3.x they detect whether they are already inside a `<Field>` and `<Control>` (via the new `FormContext`) and wrap themselves if not:

```jsx
<Input value="hi" />
// → <input class="input" value="hi" />
```

**Why this changed:** wrapping `<Input>` in `<Field><Control>` is the most common pattern in Bulma forms. Making it the default lets you skip a lot of boilerplate, and the new `label`, `message`, `iconLeftName` etc. props on `<Input>` work because the wrapper exists.

**Who is affected:**

- ✅ Code that already wraps inputs in `<Field><Control><Input/></Control></Field>` — context detection skips re-wrapping. **No change.**
- ✅ CSS that targets `.input` directly or its descendants — selectors still match.

:::warning Watch for these patterns
You'll need to take action if your code does any of the following:

- DOM or snapshot tests that asserted `.input` is the root element of `<Input>`.
- CSS that targets `<Input>`'s parent or sibling (e.g. `.my-row > .input`).
- Layouts that placed `<Input>` directly inside a flex or grid container.

:::

**Migration paths:**

**Option A — adopt the new convenience props** (preferred for typical forms):

```tsx live
<Input
  label="Email"
  type="email"
  iconLeftName="envelope"
  message="We'll never share your email."
/>
```

**Option B — keep the bare-element behavior** with the new `*Base` exports:

```jsx

<InputBase value="hi" />;
// → <input class="input" value="hi" />  (same as 2.x <Input>)
```

The same pattern applies to `<Select>` (use `SelectBase`), `<TextArea>` (use `TextAreaBase`). For `<File>`, render it inside an explicit `<Control>` to skip the auto-wrap.

## `<Radio>` and `<Checkbox>` — themed styling requires extras CSS

In 2.x, `<Radio>` and `<Checkbox>` rendered as plain native inputs styled by Bulma's stock CSS:

```html
<!-- 2.x output -->
<label class="radio"> <input type="radio" name="answer" /> Yes </label>
```

In 3.x they render with a hidden native input and a custom indicator span:

```html
<!-- 3.x output -->
<label class="styled-radio radio">
  <input type="radio" name="answer" />
  <!-- visually hidden -->
  
  <!-- the visible dot/checkmark -->
  Yes
</label>
```

The custom indicator (``) needs the new bestax extras stylesheet to be visible. If you upgrade to 3.x without importing it, the radio/checkbox will appear as an invisible click target with only the label text showing.

:::caution Required CSS import — switch to `bestax.css`
The recommended approach in 3.x is to **replace your `bulma.css` import with `bestax.css`**. It's a drop-in superset: Bulma + every bestax extra (themed Radio/Checkbox, Tooltip, Sidebar, Toast, etc.) in one file.

```jsx
// Recommended: one stylesheet, includes Bulma

```

If you were doing this before:

```jsx

```

…you can drop the `bulma/css/...` line and let `bestax.css` cover both layers.

<details>
<summary>Alternative: keep your own Bulma import</summary>

If you have a customised Bulma build, a Bulma CDN link, or a non-standard Sass pipeline you don't want to disturb, import `extras.css` alongside your existing Bulma stylesheet — it ships only the bestax overrides:

```jsx

```

</details>

See [Optional new SCSS](#optional-new-scss) below for prefixed and no-helpers variants.
:::

**Why this changed:** the themed look gives you color/size variants (`<Radio color="primary" size="large">`) and consistent visual treatment that's hard to achieve with the native form controls.

### Live examples

The examples below assume the extras CSS is loaded.

#### Standalone Radio

```tsx live
<Radios name="answer1">
  <Radio defaultChecked>Yes</Radio>
  <Radio>No</Radio>
  <Radio disabled>Maybe</Radio>
</Radios>
```

#### Standalone Checkbox

```tsx live
<Checkboxes>
  <Checkbox defaultChecked>I agree to the terms</Checkbox>
  <Checkbox color="primary">Subscribe to newsletter</Checkbox>
  <Checkbox disabled>Disabled option</Checkbox>
</Checkboxes>
```

#### Radios as a controlled group

```tsx live
function example() {
  const [color, setColor] = useState('red');
  return (
    <Block>
      <Radios name="color" value={color} onChange={setColor}>
        <Radio value="red">Red</Radio>
        <Radio value="blue">Blue</Radio>
        <Radio value="green">Green</Radio>
      </Radios>
      <Paragraph mt="2">Selected: {color}</Paragraph>
    </Block>
  );
}
```

#### Checkboxes as a controlled group

```tsx live
function example() {
  const [tags, setTags] = useState(['react']);
  return (
    <Block>
      <Checkboxes name="tags" value={tags} onChange={setTags}>
        <Checkbox value="react">React</Checkbox>
        <Checkbox value="vue">Vue</Checkbox>
        <Checkbox value="svelte">Svelte</Checkbox>
      </Checkboxes>
      <Paragraph mt="2">Selected: {tags.join(', ') || '(none)'}</Paragraph>
    </Block>
  );
}
```

## `<Tabs>` — new context, but legacy API preserved

`<Tabs>` now provides a `TabsContext` to descendants. The legacy `<Tabs.Item>` (`TabItem`) **does not consume this context** and continues to behave exactly as it did in 2.x — driven by your `active` and `onClick` props:

```tsx live
function example() {
  // 2.x and 3.x — identical behavior
  const [i, setI] = useState(0);
  return (
    <Tabs>
      <Tabs.List>
        <Tabs.Item active={i === 0} onClick={() => setI(0)}>
          One
        </Tabs.Item>
        <Tabs.Item active={i === 1} onClick={() => setI(1)}>
          Two
        </Tabs.Item>
      </Tabs.List>
    </Tabs>
  );
}
```

:::note Wrap children in ``
The legacy `<Tabs.Item>` renders a `` only — Bulma's tab CSS expects an `` link inside it for the click target styling. The new `<Tabs.Tab>` component below does this for you.
:::

A new opt-in `<Tabs.Tab index={n}>` component DOES consume the context and lets you control active state via `<Tabs value={n} onChange={...}>` or uncontrolled via `<Tabs defaultValue={n}>`:

```tsx live
function example() {
  // 3.x opt-in — controlled tabs without per-item handlers
  const [tab, setTab] = useState(0);
  return (
    <Tabs value={tab} onChange={setTab}>
      <Tabs.List>
        <Tabs.Tab index={0}>One</Tabs.Tab>
        <Tabs.Tab index={1}>Two</Tabs.Tab>
      </Tabs.List>
      <Tabs.Content>
        <Tabs.Content.Item index={0}>One panel</Tabs.Content.Item>
        <Tabs.Content.Item index={1}>Two panel</Tabs.Content.Item>
      </Tabs.Content>
    </Tabs>
  );
}
```

:::note No migration required
You don't have to swap anything — pick the API that fits each callsite. The two patterns can coexist in the same project, even on the same page.
:::

## `<Field>` — subtle defaults

Two small behavior tweaks in `<Field>`:

- **`labelSize` defaults to `'normal'`** when `horizontal` is set (was `undefined → no class`). This adds `is-normal` to the FieldLabel for proper baseline alignment with the input. If you customised label alignment in horizontal layouts, verify it still looks right — or pass an explicit `labelSize`.
- **FieldBody auto-wrap detection** now also recognises `<Field.Label>` siblings as user-provided structure (previously only a single `<Field.Body>` was detected). If you were relying on Field auto-wrapping a non-standard combination of children, the rendered DOM may differ.

New additive props on `<Field>`: `narrow?: boolean` and `hasAddons` widened to `boolean | 'centered' | 'right'`.

## `<Checkboxes>` and `<Radios>` — optional state container

In 2.x these were plain wrapper divs with no state.

In 3.x they're stateful group containers _when you opt in_. If you were using them purely as visual wrappers and managing each `<Checkbox>` / `<Radio>` individually, your existing JSX keeps working — the new `name`, `value`, `defaultValue`, `onChange` props are all optional, and individual `<Checkbox checked=... onChange=...>` props always take precedence over the group context.

(Note: their child `<Checkbox>` / `<Radio>` elements still need the new extras CSS to render correctly — see [the section above](#radio-and-checkbox--themed-styling-requires-extras-css).)

The new modes:

```jsx
// Controlled
const [tags, setTags] = useState(['react']);
<Checkboxes name="tags" value={tags} onChange={setTags}>
  <Checkbox value="react">React</Checkbox>
  <Checkbox value="vue">Vue</Checkbox>
</Checkboxes>

// Uncontrolled
<Checkboxes name="tags" defaultValue={['react']}>
  <Checkbox value="react">React</Checkbox>
  <Checkbox value="vue">Vue</Checkbox>
</Checkboxes>

// Same patterns for <Radios>, but with a single string value instead of an array
```

## `<Notification>` — additive singleton API

`<Notification>` itself is unchanged in render output (one new optional prop, `textColor`, for setting text color separately from the background color). Existing JSX usage stays the same.

What's new is a programmatic singleton API:

```jsx

notification.show({ message: 'Saved!', color: 'success', duration: 3000 });
notification.success('Saved!');
notification.danger('Something went wrong');

const id = notification.show({ message: 'Loading...', indefinite: true });
notification.close(id);
```

:::tip Purely additive
Your existing `<Notification>` JSX continues to work exactly as it did in 2.x. The singleton API is just a new option, not a replacement.
:::

## Type tightening (likely no impact)

A handful of components added `Omit<HTMLAttributes, ...>` to their `extends` clauses to resolve internal type conflicts:

| Component          | Omitted prop                                                                                                                                         |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Tabs`             | `onChange` — was inherited `FormEventHandler<HTMLDivElement>`; now typed as `(index: number) => void` (opt-in helper for the new context-driven API) |
| `Loading`          | `color`, `backgroundColor`, `size` — these are now Bulma helper-prop modifiers                                                                       |
| `Modal`            | `color`, `title`                                                                                                                                     |
| `Dropdown`, `Menu` | helper-prop name collisions                                                                                                                          |

:::info Likely no impact
These only matter if you happened to spread the omitted native HTML attribute directly onto one of these components — almost no real consumer does this.
:::

## Packaging

- **`bulma` moved from `peerDependencies` to `dependencies`.** npm now installs `bulma` automatically when you install `@allxsmith/bestax-bulma` — you don't need to add it to your own `package.json`. Bulma's CSS is also bundled into the prebuilt stylesheets (`dist/bestax.css` and its prefixed / no-helpers / no-dark-mode variants), so consumers using one of those stylesheets don't need to import any other bulma CSS file. The bulma JavaScript / source files are still installed alongside (not bundled into bestax's JS), which is what enables you to `@use '@allxsmith/bestax-bulma/scss'` for custom Sass builds. If you had your own `bulma` pinned to a different `^1.x` version, npm will dedupe.
- **`sideEffects` corrected** to `["**/*.css", "**/*.scss"]` so bundlers preserve CSS imports correctly (in 2.x, aggressive tree-shakers could drop them).
- Peer dependency ranges for React (`^16.8.0 || ^17 || ^18 || ^19`) and the icon font packages (`@fortawesome/fontawesome-free`, `@mdi/font`, `ionicons`, `material-icons`, `material-symbols`) are unchanged.

## What's new

3.x ships ~30 new components. Highlights:

| Component        | Description                                                           |
| ---------------- | --------------------------------------------------------------------- |
| `<Tooltip>`      | Auto-positioned floating tooltip                                      |
| `<Carousel>`     | Slide carousel with dragging, indicators, keyboard nav                |
| `<Collapse>`     | Animated collapse / expand sections                                   |
| `<Dialog>`       | Modal dialogs with `confirm` / `alert` / `prompt` API                 |
| `<Loading>`      | Overlay spinner for any container                                     |
| `<Sidebar>`      | Slide-out side panel with overlay or inline modes                     |
| `<Toast>`        | Toast notifications with positions, queues, and action/cancel buttons |
| `<Steps>`        | Multi-step wizard navigation                                          |
| `<LinkButton>`   | Link-styled button (text / ghost / underline variants)                |
| `<Switch>`       | Bulma switch toggle                                                   |
| `<Slider>`       | Range slider with dual-thumb mode and ticks                           |
| `<Numberinput>`  | Number input with `+/–` steppers                                      |
| `<Rate>`         | Star rating with half-star precision                                  |
| `<Autocomplete>` | Filterable suggest input                                              |
| `<Taginput>`     | Multi-tag input with autocomplete                                     |

Plus text and list elements: `Code`, `Divider`, `Emphasis`, `Figure`, `Link`, `ListItem`, `OrderedList`, `Paragraph`, `Pre`, `Span`, `Strong`, `UnorderedList`.

See the component reference for full docs.

## Optional new SCSS

:::caution Required for some components, optional for the rest
None of these stylesheets are auto-imported, but `<Radio>`, `<Checkbox>`, and the new components shipped in 3.x (Tooltip, Dialog, Sidebar, Steps, Toast, Carousel, Slider, Numberinput, Rate, Autocomplete, Taginput, etc.) **require** one of these files to render correctly. If your 2.x app only used components without custom theming (Button, Card, Modal, Field, Input, etc.) and you don't adopt any of the new components, you can keep your existing CSS setup.
:::

3.x introduces an `extras.css` stylesheet with the styling for the themed and new components:

```jsx

```

There are also pre-built variations:

- `bestax.css` — Bulma + extras bundled
- `bestax-prefixed.css` — all classes prefixed with `bulma-`
- `bestax-no-helpers.css` — without Bulma helper classes
- `bestax-no-helpers-prefixed.css` — combined
- `bestax-no-dark-mode.css` — without dark-mode rules

You can also consume the SCSS source directly:

```scss
@use '@allxsmith/bestax-bulma/scss';
```

## Component-by-component breaking-change summary

For reference, here's the per-component status. Any component not listed had no behavior changes worth flagging (typically only JSDoc updates or formatting).

### components/

- `Breadcrumb`, `Card`, `Dropdown`, `Menu`, `Message`, `Modal`, `Navbar`, `Pagination`, `Panel` — **No breaking changes.** All subcomponent prop interfaces now extend `React.HTMLAttributes<...>` (a superset — accepts more native HTML attrs).
- `Card` — additionally accepts an array `footer` prop (renders multiple `card-footer-item` divs).
- `Tabs` — **Notable, not breaking.** Adds `TabsContext.Provider`, but `<Tabs.Item>` (legacy) does not consume context. New opt-in `<Tabs.Tab>` and `<Tabs.Content>` / `<Tabs.Content.Item>` for controlled/uncontrolled active state. New optional `value`, `defaultValue`, `onChange`, `vertical`, `side`, `expanded` props on `<Tabs>`.
- `Carousel`, `Collapse`, `Dialog`, `Loading`, `Sidebar`, `Steps`, `Toast`, `Tooltip` — **NEW.** `Toast` includes optional action/cancel buttons (`actionText`, `cancelText`, `onAction`, `actionType`) and an explicit close button (`closable`) — features previously split into a separate `Snackbar` component.

### elements/

- `Block`, `Box`, `Buttons`, `Content`, `Delete`, `IconText`, `Image`, `Progress`, `Skeleton`, `SubTitle`, `Table`, `Tag`, `Tags`, `Tbody`, `Td`, `Tfoot`, `Th`, `Thead`, `Title`, `Tr` — **No breaking changes.** Mostly JSDoc / formatting updates.
- `Button` — **No breaking changes.** `color` prop union expanded with `'white' | 'light' | 'dark' | 'black' | 'text' | 'ghost'`.
- `Icon` — **No breaking changes.** New optional `containerClassName` prop.
- `Notification` — **No breaking changes for JSX usage.** New optional `textColor` prop. New programmatic `notification.show()` / `.success()` / `.close()` singleton API alongside the component.
- `Code`, `Divider`, `Emphasis`, `Figure`, `Link`, `LinkButton`, `ListItem`, `OrderedList`, `Paragraph`, `Pre`, `Span`, `Strong`, `UnorderedList` — **NEW.**

### form/

- `Input`, `Select`, `TextArea`, `File` — **BREAKING.** Auto-wrap in `<Field><Control>` when not detected via context. Use `InputBase` / `SelectBase` / `TextAreaBase` (or render `<File>` inside an explicit Control) to opt out. See the section above.
- `Field` — **Notable.** New `narrow` prop, `hasAddons` widened to `boolean | 'centered' | 'right'`, `labelSize` default for horizontal changed from `undefined → no class` to `'normal'`. Now wraps content in `<FieldProvider value={true}>` (the context the form components above read).
- `Control` — **No breaking changes.** New `iconLeftName` / `iconRightName` shortcut props.
- `Checkbox`, `Radio` — **BREAKING (visual).** Now render with a hidden native input plus a custom indicator span. Requires the new extras CSS (`dist/extras.css` or `dist/bestax.css`) to render visibly. Also additively read from `useCheckboxesGroup()` / `useRadiosGroup()` context when present (with "local props always win").
- `Checkboxes`, `Radios` — **Notable, not breaking** (their JSX is the same, their child Checkbox/Radio elements still need extras CSS — see Checkbox/Radio above). Now optional state containers via new `value` / `defaultValue` / `onChange` props.
- `Autocomplete`, `FormContext`, `InputBase`, `Numberinput`, `Rate`, `SelectBase`, `Slider`, `Switch`, `Taginput`, `TextAreaBase`, `fieldProps` — **NEW.**

### helpers/

- `Config`, `Theme`, `useBulmaClasses`, `classNames` — **No breaking changes.** New optional Theme CSS-variable props (additive). New `iconLibrary` config option.

### layout/, columns/, grid/

- `Container`, `Footer`, `Hero`, `Level`, `Media`, `Section`, `Column`, `Columns`, `Cell`, `Grid` — **No breaking changes.** JSDoc / formatting updates only.

---

## bestax-bulma 3.x → 4.x

# Upgrading bestax-bulma 3.x → 4.x

This guide explains what changes when you upgrade `@allxsmith/bestax-bulma` from 3.x to 4.x. There is **one** consumer-facing change: the minimum supported React version is now 18. Everything else in this release is internal tooling and has no effect on your code.

## TL;DR

:::tip One thing to check
4.x drops support for **React 16 and 17**. If your app is already on React 18 or 19, upgrade freely — nothing in your code needs to change. If you're still on React 16 or 17, stay on `@allxsmith/bestax-bulma@3` until you can move to React 18+.
:::

| Area               | What changed                                                        | Action               |
| ------------------ | ------------------------------------------------------------------- | -------------------- |
| React peer range   | Now `^18.0.0 \|\| ^19.0.0` (was `^16.8 \|\| ^17 \|\| ^18 \|\| ^19`) | Be on React 18 or 19 |
| Component behavior | No changes                                                          | None                 |
| Props / exports    | No removals or renames                                              | None                 |
| CSS / SCSS         | No changes                                                          | None                 |

## The one breaking change: React 18 minimum

4.x sets the React `peerDependencies` range to:

```json
"react": "^18.0.0 || ^19.0.0",
"react-dom": "^18.0.0 || ^19.0.0"
```

React 16.8 and 17 are no longer supported. The library is built and tested against **React 18 and 19** on every commit (see [Compatibility](#compatibility-react-18--19) below).

**Who is affected:**

- ✅ On React 18 or 19 — upgrade with no code changes. Your existing components, props, imports, and CSS all behave exactly as they did in 3.x.
- ⚠️ On React 16 or 17 — `pnpm add @allxsmith/bestax-bulma@4` will emit a peer-dependency warning, and some components rely on hooks/behavior that assume a modern React. **Stay on `@3`** until you can upgrade React:

  ```bash
  pnpm add @allxsmith/bestax-bulma@^3
  ```

**Why this changed:** dropping the legacy React versions lets the library use modern React idioms (e.g. `useId` for accessible, SSR-safe element IDs) without compatibility shims, and keeps the maintenance surface focused on the versions the ecosystem actually runs.

## Compatibility: React 18 + 19

Every change to bestax-bulma is now built, type-checked, and tested against **both React 18 and React 19** in CI. A change that breaks either major fails the build, so 4.x (and every release after it) is verified against both lines — pick whichever your app uses.

## No other changes

There are **no** component, prop, export, or CSS changes in 4.x:

- No components were removed, renamed, or had behavior changed.
- No props were removed or renamed.
- The stylesheets (`extras.css`, `bestax.css`, and the prefixed / no-helpers / no-dark-mode variants) and the SCSS entry points are unchanged.

The rest of the 4.0 work was internal developer tooling (ESLint 10, a TypeScript-first React lint plugin, and the expanded React Hooks ruleset). None of it ships in the package or affects consumers.

:::note Coming from 2.x?
If you're upgrading across two majors, read the [2.x → 3.x guide](./bulma-ui-2-to-3.md) first — that release carried the form-input and themed Radio/Checkbox changes. The 2→3 jump is where the real work is; 3→4 is just the React floor.
:::

---

## Migration


:::note Independent migration paths
The pages below cover unrelated upgrades. Most readers only need one. The 3.x → 4.x bump is a one-line change for most apps; the real work (if any) is in 2.x → 3.x.
:::

Pick whichever applies to your situation:

## [Upgrading bestax-bulma 3.x → 4.x](./bulma-ui-3-to-4.md)

The 4.x release has a single consumer-facing change: the **minimum supported React version is now 18** (React 16 and 17 are dropped). If your app is on React 18 or 19, upgrade with no code changes. Every release is now built and tested against both React 18 and 19. The rest of 4.0 was internal tooling and ships nothing that affects your code.

[Read the full 3.x to 4.x guide →](./bulma-ui-3-to-4.md)

## [Upgrading bestax-bulma 2.x → 3.x](./bulma-ui-2-to-3.md)

The 3.x release is **mostly additive** — about 30 new components plus quality-of-life prop additions. Two changes need active attention:

- **Form input auto-wrap**: `<Input>`, `<Select>`, `<TextArea>`, and `<File>` now compose themselves with `<Field>` and `<Control>` automatically. If you already wrap inputs in `<Field><Control>`, nothing changes; new `InputBase` / `SelectBase` / `TextAreaBase` exports preserve the bare-element behavior for the rest.
- **Themed `<Radio>` and `<Checkbox>`** now use a custom-styled indicator that requires the new bestax extras CSS to render visibly. Import `dist/extras.css` or `dist/bestax.css`.

Also notable but not breaking: new optional context-driven APIs in `<Tabs>`, `<Checkboxes>`, and `<Radios>`; a new programmatic singleton API in `<Notification>`; and `bulma` moves from `peerDependencies` to `dependencies`.

[Read the full 2.x to 3.x guide →](./bulma-ui-2-to-3.md)

## [Migrating from Bulma v0.9.x → v1](./bulma-0-9-to-1.md)

bestax-bulma itself has always required Bulma v1 — there's no "bestax on Bulma 0.9" path. This guide is for two adjacent scenarios: (1) you're migrating off **another** React + Bulma library (`react-bulma-components`, Buefy, etc.) that was pinned to Bulma 0.9.x, or (2) you have **plain Bulma 0.9.x** in your own project that you want to upgrade alongside (or before) adopting bestax.

The HTML stays identical between Bulma 0.9 and 1, but Bulma v1 swaps Node Sass for Dart Sass, introduces CSS custom properties for runtime theming, ships a real CSS Grid system, and deprecates Tiles.

[Read the full Bulma 0.9.4 → 1.x guide →](./bulma-0-9-to-1.md)

---

## Modular


This guide covers how to trim your CSS and JS bundles by importing only what you use from bestax-bulma and Bulma.

:::tip Recommended default
For most projects, import the combined bundle and let React handle the rest:

```js

```

`bestax.css` is already minified and small, and modern bundlers tree-shake unused components from the JS side automatically. You only need to go modular if you've measured CSS size and have a specific constraint to hit.
:::

Modular optimization has two independent axes:

1. **JS bundle** — handled by your bundler's tree shaking. Just use named imports.
2. **CSS bundle** — handled by choosing one of the CSS options below (combined, extras-only, or hand-rolled SCSS).

## JS: named imports and tree shaking

bestax-bulma is published as ES modules with `"sideEffects": ["**/*.css", "**/*.scss"]` in its `package.json`. That means Vite, Webpack 5, Rollup, esbuild, Next.js, and other modern bundlers strip out any component you don't reference — no extra configuration required.

```tsx
// Good — only the components you name are bundled

```

:::warning Don't default-import the whole library
This defeats tree shaking and pulls in every component:

```tsx
// Bad — forces the whole library into your bundle

```

:::

### Component categories

Components are organized by Bulma category. Import from the same package path regardless of category:

```tsx

  ConfigProvider,
  Theme,
  useBulmaClasses,
} from '@allxsmith/bestax-bulma'; // Helpers
```

:::info Full export list
The categories above are illustrative, not exhaustive. See the [Elements](/docs/category/elements), [Components](/docs/category/components), [Form](/docs/category/form), [Layout](/docs/category/layout), [Columns](/docs/api/columns), and [Grid](/docs/api/grid) API sections for the complete list, including newer additions like `Dialog`, `Carousel`, `Tooltip`, `Steps`, `Sidebar`, `Toast`, `Loading`, `Collapse`, `Autocomplete`, `Taginput`, `Rate`, `Slider`, `NumberInput`, `Switch`, `Checkboxes`, and `Radios`.
:::

## CSS: three ways to load styles

### Option A — combined bundle (recommended)

One import gives you Bulma and all bestax extras:

```js

```

:::tip This is the right choice for almost every project
`bestax.css` is already minified. After gzip/Brotli, the difference between it and a hand-tuned modular build is usually a few KB — not worth the ongoing maintenance of keeping SCSS imports in sync as you add components. Start here, then measure before optimizing further.
:::

### Option B — Bulma + extras separately

If you're already managing Bulma's CSS yourself (e.g. using a specific variant, CDN, or custom theme build), add only the bestax extras on top:

```js

```

`extras.css` contains only the styles for components bestax adds on top of Bulma (Dialog, Carousel, Tooltip, Autocomplete, etc.).

### Option C — hand-rolled modular SCSS (advanced)

:::caution Advanced — only if you've measured
Hand-rolling modular SCSS is worthwhile only when you have a demonstrated CSS-size budget. You take on the maintenance burden of keeping imports in sync with the components you actually use. If in doubt, use Option A.
:::

Install Sass as a dev dependency (Bulma is already installed as a transitive dependency):

```bash
pnpm add -D sass
```

#### Required base styles

Before importing component partials, include Bulma's base (CSS reset, generic element styles, keyframes) and themes (CSS custom properties on `:root`):

```scss
// Required: reset + CSS variable definitions
@use 'bulma/sass/base';
@use 'bulma/sass/themes';
```

- `base` provides `minireset`, generic element styles, and animation keyframes.
- `themes` registers the `--bulma-*` CSS custom properties (colors, radii, `--bulma-scheme-main`, etc.) and sets up light/dark mode.

:::info Exception: grid and columns
`bulma/sass/grid/columns` and `bulma/sass/grid/grid` register their own CSS variables internally and compile their breakpoints from SCSS, so they can technically be used without `base` and `themes`. The safe default is still to include both — you'll almost always want them as soon as you add a second component.
:::

#### Bulma component partials

After the base, `@use` only the Bulma partials you need:

```scss
// Elements
@use 'bulma/sass/elements/button';
@use 'bulma/sass/elements/box';
@use 'bulma/sass/elements/notification';
@use 'bulma/sass/elements/title';

// Form
@use 'bulma/sass/form/input';
@use 'bulma/sass/form/textarea';
@use 'bulma/sass/form/select';

// Components
@use 'bulma/sass/components/card';
@use 'bulma/sass/components/modal';
@use 'bulma/sass/components/navbar';

// Grid systems
@use 'bulma/sass/grid/columns';
@use 'bulma/sass/grid/grid';

// Layout
@use 'bulma/sass/layout/container';
@use 'bulma/sass/layout/section';
```

Pull in only the helper categories you use:

```scss
@use 'bulma/sass/helpers/spacing';
@use 'bulma/sass/helpers/color';
@use 'bulma/sass/helpers/typography';
@use 'bulma/sass/helpers/flexbox';
@use 'bulma/sass/helpers/other';
```

#### bestax extras partials

bestax ships SCSS partials for every component it adds on top of Bulma. Import them the same way via the package's `scss/*` export:

```scss
// bestax components
@use '@allxsmith/bestax-bulma/scss/components/dialog';
@use '@allxsmith/bestax-bulma/scss/components/carousel';
@use '@allxsmith/bestax-bulma/scss/components/tooltip';
@use '@allxsmith/bestax-bulma/scss/components/loading';
@use '@allxsmith/bestax-bulma/scss/components/collapse';
@use '@allxsmith/bestax-bulma/scss/components/sidebar';
@use '@allxsmith/bestax-bulma/scss/components/toast';
@use '@allxsmith/bestax-bulma/scss/components/steps';
@use '@allxsmith/bestax-bulma/scss/components/tabs';

// bestax form components
@use '@allxsmith/bestax-bulma/scss/form/autocomplete';
@use '@allxsmith/bestax-bulma/scss/form/taginput';
@use '@allxsmith/bestax-bulma/scss/form/rate';
@use '@allxsmith/bestax-bulma/scss/form/slider';
@use '@allxsmith/bestax-bulma/scss/form/numberinput';
@use '@allxsmith/bestax-bulma/scss/form/switch';
@use '@allxsmith/bestax-bulma/scss/form/checkbox';
@use '@allxsmith/bestax-bulma/scss/form/radio';

// bestax elements and helpers
@use '@allxsmith/bestax-bulma/scss/elements/linkbutton';
@use '@allxsmith/bestax-bulma/scss/helpers/cursor';
@use '@allxsmith/bestax-bulma/scss/helpers/sizing';
```

:::info Shortcuts

- `@use '@allxsmith/bestax-bulma/scss/bestax'` — SCSS source for the full combined bundle (Bulma + all extras). Use this instead of `bestax.css` when you want a single SCSS entry point that participates in your Sass build.
- `@use '@allxsmith/bestax-bulma/scss'` — extras only (equivalent to `extras.css` but from source).
  :::

#### Complete example

A realistic modular SCSS entry for an app that uses a few Bulma primitives plus bestax's Dialog and Autocomplete:

```scss
// src/styles/app.scss

// Required base
@use 'bulma/sass/base';
@use 'bulma/sass/themes';

// Bulma partials — only what the app uses
@use 'bulma/sass/elements/button';
@use 'bulma/sass/elements/box';
@use 'bulma/sass/elements/title';
@use 'bulma/sass/form/input';
@use 'bulma/sass/components/card';
@use 'bulma/sass/grid/columns';
@use 'bulma/sass/helpers/spacing';
@use 'bulma/sass/helpers/color';

// bestax extras — only what the app uses
@use '@allxsmith/bestax-bulma/scss/components/dialog';
@use '@allxsmith/bestax-bulma/scss/form/autocomplete';
```

Then import the compiled stylesheet once in your app entry:

```tsx
// src/App.tsx

  Button,
  Box,
  Card,
  Columns,
  Column,
  Title,
  Dialog,
  Autocomplete,
} from '@allxsmith/bestax-bulma';

function App() {
  return (
    <Columns>
      <Column>
        <Card>
          <Box p="4">
            <Title>Modular App</Title>
            <Button color="primary">Go</Button>
          </Box>
        </Card>
      </Column>
    </Columns>
  );
}

export default App;
```

## Prebuilt variants

If you want something smaller than `bestax.css` without writing SCSS, bestax ships a handful of prebuilt variants as a middle ground:

```js
// Bulma + extras, all classes prefixed with `bestax-` (pair with classPrefix="bestax-")

// Combined bundle without Bulma's helper classes (saves a lot of CSS)

// Same, `bestax-` prefixed

// Combined bundle without dark-mode rules

```

These require no SCSS toolchain — swap the import path and you're done.

## Bundle size expectations

- **`bestax.css`**: ~80KB gzipped (Bulma + extras, minified). Fine for most apps.
- **Hand-rolled modular SCSS**: can cut that significantly if you only use a handful of components, but expect diminishing returns after gzip.
- **JS bundle**: tree shaking is automatic with named imports — you don't need to do anything beyond avoiding `import * as ...`.

## When to go modular

Use this checklist before switching away from `bestax.css`:

1. **Ship first with `bestax.css`.** Don't premature-optimize — many apps never need anything else.
2. **Measure.** Use `webpack-bundle-analyzer`, `rollup-plugin-visualizer`, or your bundler's built-in stats to confirm CSS size is actually a problem.
3. **Try a prebuilt variant** (`bestax-no-helpers.css`, `bestax-no-dark-mode.css`) before reaching for SCSS — often enough to hit the target.
4. **Only then reach for modular SCSS**, and keep the imports in a single entry file so they're easy to audit as the app grows.

---

## Toolchains


Start a new project with your framework's own scaffolder (Vite, `create-next-app`, or CRA) and wire bestax-bulma in. Pick this guide if you want full control over your toolchain.

:::tip Looking for the easy path?

- **[Quick Start](/docs/guides/intro)** — run `pnpm create bestax@latest` and the scaffolder sets up a Vite + React project with bestax-bulma and CSS pre-configured. Done in two minutes.
- **[Installation](/docs/guides/getting-started/installation)** — adding bestax-bulma to an existing app, or choosing between the combined `bestax.css` bundle, separate CSS, CDN, or a custom SCSS build. Covers icon libraries too.

Use the per-framework walkthroughs below only if neither of those fits.
:::

---

## ❤️ Vite + React + Bulma + bestax-bulma

Vite is a modern, fast build tool that's become the go-to choice for React applications. Here's how to set up bestax-bulma with Vite.

### JavaScript Example

1. **Create a new Vite React project:**

   ```bash
   pnpm create vite@latest my-bulma-vite-app -- --template react
   cd my-bulma-vite-app
   pnpm install
   ```

   :::info Template Argument Explained
   - `--template react`: Uses the official React template with JavaScript
   - Alternative templates: `react-ts` (TypeScript), `react-swc` (with SWC compiler)
   - The `--` separates npm arguments from Vite create arguments
     :::

   :::tip Vite Documentation
   For more details about `pnpm create vite` and available templates, see the [official Vite documentation](https://vitejs.dev/guide/#scaffolding-your-first-vite-project).
   :::

2. **Install bestax-bulma and dependencies:**

   ```bash
   pnpm add @allxsmith/bestax-bulma @fortawesome/fontawesome-free
   ```

3. **Update your main.jsx file:**

   ```jsx title="src/main.jsx"

   // Import Bestax CSS (includes Bulma + extras)

   // Import Font Awesome

   createRoot(document.getElementById('root')).render(
     <StrictMode>
       <App />
     </StrictMode>
   );
   ```

4. **Update your App.jsx:**

   ```jsx title="src/App.jsx"

     Box,
     Button,
     Title,
     SubTitle,
     Icon,
     Notification,
     Columns,
     Column,
     Container,
     Section,
   } from '@allxsmith/bestax-bulma';

   function App() {
     const [showNotification, setShowNotification] = useState(false);

     return (
       <Container>
         <Section>
           <Box textAlign="centered">
             <Title size="1" textAlign="centered">
               🚀 Vite + React + bestax-bulma
             </Title>

             <SubTitle size="4" textAlign="centered" color="grey">
               Modern React development with Bulma components
             </SubTitle>

             <Columns isCentered mt="5">
               <Column size="half">
                 <Button
                   color="primary"
                   size="large"
                   onClick={() => setShowNotification(!showNotification)}
                 >
                   <Icon name="magic" />
                   Toggle Notification
                 </Button>

                 {showNotification && (
                   <Notification color="success" mt="4">
                     <Icon name="check-circle" />
                     Success! Your Vite + React + bestax-bulma
                     setup is working perfectly!
                   </Notification>
                 )}
               </Column>
             </Columns>
           </Box>
         </Section>
       </Container>
     );
   }

   export default App;
   ```

5. **Run your application:**

   ```bash
   pnpm dev
   ```

   :::tip Application Available
   Your Vite + React + bestax-bulma application will be available at `http://localhost:5173`
   :::

### TypeScript Example

1. **Create a new Vite React TypeScript project:**

   ```bash
   pnpm create vite@latest my-bulma-vite-ts-app -- --template react-ts
   cd my-bulma-vite-ts-app
   pnpm install
   ```

   :::info Template Argument Explained
   - `--template react-ts`: Uses the official React template with TypeScript
   - Includes TypeScript configuration and type definitions out of the box
   - Alternative: `react-swc-ts` (TypeScript with SWC compiler for faster builds)
     :::

   :::tip Vite Documentation
   For more details about `pnpm create vite` and available templates, see the [official Vite documentation](https://vitejs.dev/guide/#scaffolding-your-first-vite-project).
   :::

2. **Install bestax-bulma and dependencies:**

   ```bash
   pnpm add @allxsmith/bestax-bulma @fortawesome/fontawesome-free
   ```

   :::note
   The `react-ts` template already includes `@types/react` and `@types/react-dom` — no extra type packages needed.
   :::

3. **Update your main.tsx file:**

   ```tsx title="src/main.tsx"

   // Import Bestax CSS (includes Bulma + extras)

   // Import Font Awesome

   createRoot(document.getElementById('root')!).render(
     <StrictMode>
       <App />
     </StrictMode>
   );
   ```

4. **Update your App.tsx:**

   ```tsx title="src/App.tsx"

     Box,
     Button,
     Title,
     SubTitle,
     Icon,
     Notification,
     Columns,
     Column,
     Container,
     Section,
   } from '@allxsmith/bestax-bulma';

   function App() {
     const [showNotification, setShowNotification] = useState<boolean>(false);

     return (
       <Container>
         <Section>
           <Box textAlign="centered">
             <Title size="1" textAlign="centered">
               🚀 Vite + React + bestax-bulma
             </Title>

             <SubTitle size="4" textAlign="centered" color="grey">
               Modern TypeScript React development with Bulma components
             </SubTitle>

             <Columns isCentered mt="5">
               <Column size="half">
                 <Button
                   color="primary"
                   size="large"
                   onClick={() => setShowNotification(!showNotification)}
                 >
                   <Icon name="magic" />
                   Toggle Notification
                 </Button>

                 {showNotification && (
                   <Notification color="success" mt="4">
                     <Icon name="check-circle" />
                     Success! Your Vite + React + bestax-bulma
                     TypeScript setup is working perfectly!
                   </Notification>
                 )}
               </Column>
             </Columns>
           </Box>
         </Section>
       </Container>
     );
   }

   export default App;
   ```

5. **Run your application:**

   ```bash
   pnpm dev
   ```

   :::tip Application Available
   Your Vite + React + TypeScript + bestax-bulma application will be available at `http://localhost:5173`
   :::

---

## Next.js

Next.js is a popular React framework that provides server-side rendering, static site generation, and many other features out of the box.

### JavaScript Example (Next.js 13+ with App Router)

1. **Create a new Next.js project:**

   ```bash
   pnpm dlx create-next-app@latest my-bulma-next-app --js --eslint --no-tailwind --src-dir --app --import-alias "@/*" --turbopack
   cd my-bulma-next-app
   ```

   :::info Command Arguments Explained
   - `--js`: Use JavaScript (not TypeScript)
   - `--eslint`: Include ESLint for code quality
   - `--no-tailwind`: Skip Tailwind CSS (we're using Bulma!)
   - `--src-dir`: Create a `src/` directory for better organization
   - `--app`: Use App Router (recommended for Next.js 13+)
   - `--import-alias "@/*"`: Set up path alias for cleaner imports
   - `--turbopack`: Use Turbopack (experimental, faster development)
     :::

   :::tip Next.js Documentation
   For more details about `create-next-app` options, see the [official Next.js documentation](https://nextjs.org/docs/app/api-reference/create-next-app).
   :::

2. **Install bestax-bulma and dependencies:**

   ```bash
   pnpm add @allxsmith/bestax-bulma @fortawesome/fontawesome-free
   ```

3. **Update your root layout:**

   ```jsx title="src/app/layout.js"
   // Import Bestax CSS globally (includes Bulma + extras)

   export const metadata = {
     title: 'Next.js + bestax-bulma',
     description: 'Next.js application with Bulma components',
   };

   export default function RootLayout({ children }) {
     return (
       <html lang="en">
         <body>{children}</body>
       </html>
     );
   }
   ```

4. **Update your main page:**

   ```jsx title="src/app/page.js"
   'use client';

     Box,
     Button,
     Title,
     SubTitle,
     Icon,
     Notification,
     Columns,
     Column,
     Container,
     Section,
   } from '@allxsmith/bestax-bulma';
   // Uncomment if you want to use CSS modules within this page
   // Note: this page.modules.css has some styles you should review since
   //       they may not pertain to our example
   // import styles from "./page.module.css";

   export default function Home() {
     const [showNotification, setShowNotification] = useState(false);

     return (
       <Container>
         <Section>
           <Box textAlign="centered">
             <Title size="1" textAlign="centered">
               🚀 Next.js + React + bestax-bulma
             </Title>

             <SubTitle size="4" textAlign="centered" color="grey">
               Server-side rendering with Bulma components
             </SubTitle>

             <Columns isCentered mt="5">
               <Column size="half">
                 <Button
                   color="primary"
                   size="large"
                   onClick={() => setShowNotification(!showNotification)}
                 >
                   <Icon name="magic" />
                   Toggle Notification
                 </Button>

                 {showNotification && (
                   <Notification color="success" mt="4">
                     <Icon name="check-circle" />
                     Success! Your Next.js + React +
                     bestax-bulma setup is working perfectly!
                   </Notification>
                 )}
               </Column>
             </Columns>
           </Box>
         </Section>
       </Container>
     );
   }
   ```

5. **Run your application:**

   ```bash
   pnpm dev
   ```

   :::tip Application Available
   Your Next.js + React + bestax-bulma application will be available at `http://localhost:3000`
   :::

### TypeScript Example (Next.js 13+ with App Router)

1. **Create a new Next.js TypeScript project:**

   ```bash
   pnpm dlx create-next-app@latest my-bulma-next-ts-app --ts --eslint --no-tailwind --src-dir --app --import-alias "@/*" --turbopack
   cd my-bulma-next-ts-app
   ```

   :::info Command Arguments Explained
   - `--ts`: Use TypeScript (not JavaScript)
   - `--eslint`: Include ESLint for code quality
   - `--no-tailwind`: Skip Tailwind CSS (we're using Bulma!)
   - `--src-dir`: Create a `src/` directory for better organization
   - `--app`: Use App Router (recommended for Next.js 13+)
   - `--import-alias "@/*"`: Set up path alias for cleaner imports
   - `--turbopack`: Use Turbopack (experimental, faster development)
     :::

   :::tip Next.js Documentation
   For more details about `create-next-app` options, see the [official Next.js documentation](https://nextjs.org/docs/app/api-reference/create-next-app).
   :::

2. **Install bestax-bulma and dependencies:**

   ```bash
   pnpm add @allxsmith/bestax-bulma @fortawesome/fontawesome-free
   ```

3. **Update your root layout:**

   ```tsx title="src/app/layout.tsx"

   // Import Bestax CSS globally (includes Bulma + extras)

   export const metadata: Metadata = {
     title: 'Next.js + bestax-bulma',
     description: 'Next.js TypeScript application with Bulma components',
   };

   export default function RootLayout({
     children,
   }: {
     children: React.ReactNode;
   }) {
     return (
       <html lang="en">
         <body>{children}</body>
       </html>
     );
   }
   ```

4. **Update your main page:**

   ```tsx title="src/app/page.tsx"
   'use client';

     Box,
     Button,
     Title,
     SubTitle,
     Icon,
     Notification,
     Columns,
     Column,
     Container,
     Section,
   } from '@allxsmith/bestax-bulma';
   // Uncomment if you want to use CSS modules within this page
   // Note: this page.modules.css has some styles you should review since
   //       they may not pertain to our example
   // import styles from "./page.module.css";
   export default function Home() {
     const [showNotification, setShowNotification] = useState<boolean>(false);

     return (
       <Container>
         <Section>
           <Box textAlign="centered">
             <Title size="1" textAlign="centered">
               🚀 Next.js + React + bestax-bulma
             </Title>

             <SubTitle size="4" textAlign="centered" color="grey">
               Server-side rendering with TypeScript and Bulma components
             </SubTitle>

             <Columns isCentered mt="5">
               <Column size="half">
                 <Button
                   color="primary"
                   size="large"
                   onClick={() => setShowNotification(!showNotification)}
                 >
                   <Icon name="magic" />
                   Toggle Notification
                 </Button>

                 {showNotification && (
                   <Notification color="success" mt="4">
                     <Icon name="check-circle" />
                     Success! Your Next.js TypeScript +
                     bestax-bulma setup is working perfectly!
                   </Notification>
                 )}
               </Column>
             </Columns>
           </Box>
         </Section>
       </Container>
     );
   }
   ```

5. **Run your application:**

   ```bash
   pnpm dev
   ```

   :::tip Application Available
   Your Next.js + TypeScript + bestax-bulma application will be available at `http://localhost:3000`
   :::

---

## CRA and Other Legacy Bundlers

:::warning Create React App is deprecated
The React team [officially sunsetted Create React App in February 2025](https://react.dev/blog/2025/02/14/sunsetting-create-react-app). For new projects, use [Vite](#️-vite--react--bulma--bestax-bulma) or [Next.js](#nextjs) instead. The instructions below are kept for teams maintaining existing CRA apps.
:::

For Create React App and other legacy bundlers like Webpack 4, the setup process is slightly different.

### JavaScript Example (Create React App)

1. **Create a new CRA project:**

   ```bash
   pnpm dlx create-react-app my-bulma-cra-app
   cd my-bulma-cra-app
   ```

2. **Install bestax-bulma and dependencies:**

   ```bash
   pnpm add @allxsmith/bestax-bulma @fortawesome/fontawesome-free
   ```

3. **Update your index.js:**

   ```jsx title="src/index.js"

   // Import Bestax CSS (includes Bulma + extras)

   // Import Font Awesome

   // Import default CRA styles last

   const root = ReactDOM.createRoot(document.getElementById('root'));
   root.render(
     <React.StrictMode>
       <App />
     </React.StrictMode>
   );

   // If you want to start measuring performance in your app, pass a function
   // to log results (for example: reportWebVitals(console.log))
   // or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
   reportWebVitals();
   ```

4. **Update your App.js:**

   ```jsx title="src/App.js"

     Box,
     Button,
     Title,
     SubTitle,
     Icon,
     Notification,
     Columns,
     Column,
     Container,
     Section,
   } from '@allxsmith/bestax-bulma';

   function App() {
     const [showNotification, setShowNotification] = useState(false);

     return (
       <Container>
         <Section>
           <Box textAlign="centered">
             <Title size="1" textAlign="centered">
               🚀 Create React App + bestax-bulma
             </Title>

             <SubTitle size="4" textAlign="centered" color="grey">
               Client-side rendering with JavaScript and Bulma components
             </SubTitle>

             <Columns isCentered mt="5">
               <Column size="half">
                 <Button
                   color="primary"
                   size="large"
                   onClick={() => setShowNotification(!showNotification)}
                 >
                   <Icon name="magic" />
                   Toggle Notification
                 </Button>

                 {showNotification && (
                   <Notification color="success" mt="4">
                     <Icon name="check-circle" />
                     Success! Your Create React App +
                     bestax-bulma setup is working perfectly!
                   </Notification>
                 )}
               </Column>
             </Columns>
           </Box>
         </Section>
       </Container>
     );
   }

   export default App;
   ```

5. **Run your application:**

   ```bash
   npm start
   ```

   :::tip Application Available
   Your Create React App + bestax-bulma application will be available at `http://localhost:3000`
   :::

### TypeScript Example (Create React App)

1. **Create a new CRA TypeScript project:**

   ```bash
   pnpm dlx create-react-app my-bulma-cra-ts-app --template typescript
   cd my-bulma-cra-ts-app
   ```

2. **Install bestax-bulma and dependencies:**

   ```bash
   pnpm add @allxsmith/bestax-bulma @fortawesome/fontawesome-free
   ```

3. **Update your index.tsx:**

   ```tsx title="src/index.tsx"

   // Import Bestax CSS (includes Bulma + extras)

   // Import Font Awesome

   // Import default CRA styles last

   const root = ReactDOM.createRoot(
     document.getElementById('root') as HTMLElement
   );
   root.render(
     <React.StrictMode>
       <App />
     </React.StrictMode>
   );

   // If you want to start measuring performance in your app, pass a function
   // to log results (for example: reportWebVitals(console.log))
   // or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
   reportWebVitals();
   ```

4. **Update your App.tsx:**

   ```tsx title="src/App.tsx"

     Box,
     Button,
     Title,
     SubTitle,
     Icon,
     Notification,
     Columns,
     Column,
     Container,
     Section,
   } from '@allxsmith/bestax-bulma';

   const App: React.FC = () => {
     const [showNotification, setShowNotification] = useState<boolean>(false);

     return (
       <Container>
         <Section>
           <Box textAlign="centered">
             <Title size="1" textAlign="centered">
               🚀 Create React App + bestax-bulma
             </Title>

             <SubTitle size="4" textAlign="centered" color="grey">
               Client-side rendering with TypeScript and Bulma components
             </SubTitle>

             <Columns isCentered mt="5">
               <Column size="half">
                 <Button
                   color="primary"
                   size="large"
                   onClick={() => setShowNotification(!showNotification)}
                 >
                   <Icon name="magic" />
                   Toggle Notification
                 </Button>

                 {showNotification && (
                   <Notification color="success" mt="4">
                     <Icon name="check-circle" />
                     Success! Your Create React App TypeScript
                     + bestax-bulma setup is working perfectly!
                   </Notification>
                 )}
               </Column>
             </Columns>
           </Box>
         </Section>
       </Container>
     );
   };

   export default App;
   ```

5. **Run your application:**

   ```bash
   npm start
   ```

   :::tip Application Available
   Your Create React App + TypeScript + bestax-bulma application will be available at `http://localhost:3000`
   :::

---

## SSR (Server-Side Rendering)

bestax-bulma is designed to work seamlessly with SSR frameworks. Here are some important considerations:

### General SSR Guidelines

1. **CSS Import Strategy**: Always import Bulma CSS at the application level (not component level) to ensure consistent styling during hydration.

2. **Hydration Compatibility**: All bestax-bulma components are designed to render identically on server and client, preventing hydration mismatches.

3. **No Browser Dependencies**: bestax-bulma components don't rely on browser-specific APIs during initial render, making them SSR-safe.

### Next.js Specific

```tsx
// ✅ Good: Import CSS in layout.tsx (App Router) or _app.tsx (Pages Router)

// ❌ Avoid: Importing CSS in individual components
// This can cause CSS to load after component render
```

### Remix

```tsx title="app/root.tsx"

export const links: LinksFunction = () => [
  { rel: 'stylesheet', href: bestaxStyles },
];
```

:::note
Remix v2+ requires the `?url` suffix on CSS imports used in `LinksFunction`.
:::

### Gatsby

```tsx title="gatsby-browser.js"

```

---

## Troubleshooting

### Syntax Errors

**Problem**: TypeScript errors when using bestax-bulma components.

**Solution**: Ensure you have the latest TypeScript version and proper type declarations:

```bash
pnpm add -D typescript @types/react @types/react-dom
```

### Tree Shaking Issues

**Problem**: Large bundle size when importing bestax-bulma.

**Solution**: Use named imports instead of default imports:

```tsx
// ✅ Good: Named imports (tree-shakeable)

// ❌ Avoid: Default import (includes entire library)

```

### Responsiveness Issues

**Problem**: Components don't respond properly on mobile devices.

**Solution**: Ensure the viewport meta tag is present in your HTML:

```html
<meta name="viewport" content="width=device-width, initial-scale=1" />
```

### CSS Loading Order

**Problem**: Bulma styles are overridden by other CSS.

**Solution**: Import the bestax stylesheet before your custom styles:

```tsx
// ✅ Correct order

```

### Migration from Other Libraries

**Problem**: Migrating from react-bulma or other Bulma React libraries.

**Solution**: bestax-bulma uses similar prop names but with modern React patterns:

```tsx
// Old library
<Button isColor="primary" isSize="large" />

// bestax-bulma
<Button color="primary" size="large" />
```

### Performance Optimization

For production builds, consider:

1. **Bundle Analysis**: Use tools like `webpack-bundle-analyzer` to identify large dependencies
2. **CSS Purging**: Use PurgeCSS to remove unused Bulma styles
3. **Component Lazy Loading**: Load heavy components dynamically

```tsx
// Lazy load heavy components
const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
```

---

## Next Steps

- **Explore Components**: Browse the [API documentation](/docs/category/elements) to see all available components
- **Learn Configuration**: Read about [ConfigProvider](/docs/api/helpers/config) for global settings
- **Customize with Theming**: Discover [Theme](/docs/api/helpers/theme) for advanced customization
- **Check Examples**: Visit our [Storybook](https://bestax.io/storybook) for live component examples

---

## Syntax


This guide introduces you to how Bulma works and how our React components relate to Bulma's class-based system.

:::info Styles already loaded?
Every helper, modifier, and example on this page works as soon as you've imported `@allxsmith/bestax-bulma/bestax.css` (one stylesheet covers Bulma + bestax extras). See the [Quick Start](/docs/guides/intro) or [Installation](/docs/guides/getting-started/installation) if you haven't set that up yet.
:::

## Bulma Syntax

Bulma is a CSS framework that uses modifier classes to control the appearance and behavior of components. Understanding Bulma's syntax is essential to effectively using this React library.

### Basic Button Example

Here's how a button works in Bulma HTML:

```html

  <button class="button is-small">Button</button>

  <button class="button is-primary">Primary</button>

  <button class="button is-info">
    
      
    
    GitHub
  </button>

  <button class="button is-danger">
    
      
    
    Bold
  </button>

  <button class="button is-link is-medium">Medium Button</button>

  <!-- Rounded loading button -->
  <button class="button is-warning is-large is-rounded is-loading">
    Loading
  </button>

```

### Form Field Example (Testing Dark/Light Mode)

Here's a test example to verify our dark/light mode works with Field labels:

:::tip Test Dark/Light Mode Toggle

Try toggling between light and dark mode using the theme switcher in the top navigation bar. Notice how the field labels change color to maintain proper contrast and readability in both modes.

:::

```tsx live
<>
  <Field label="Name">
    <Control>
      <Input placeholder="Enter your name" />
    </Control>
  </Field>

  <Field label="Email">
    <Control>
      <Input placeholder="Enter your email" />
    </Control>
  </Field>

  <Field label="Message">
    <Control>
      <TextArea placeholder="Enter your message" rows={3} />
    </Control>
  </Field>
</>
```

### Modifier Classes

Bulma uses modifier classes that follow consistent patterns:

- **Color modifiers**: `is-primary`, `is-info`, `is-success`, `is-warning`, `is-danger`
- **Size modifiers**: `is-small`, `is-normal`, `is-medium`, `is-large`
- **State modifiers**: `is-loading`, `is-active` (note: disabled state uses the HTML `disabled` attribute, not a class)
- **Style modifiers**: `is-rounded`, `is-outlined`, `is-inverted`

### Combining Modifiers

Modifiers can be combined to create complex styling:

```html
<button class="button is-primary is-large is-outlined is-rounded">
  Fancy Button
</button>
```

Or, in this library, as a single React component:

```tsx live
<Button color="primary" size="large" outlined rounded>
  Fancy Button
</Button>
```

## React Component Mapping

This React library maps properties to Bulma classes, making it easier and more type-safe to work with Bulma in React applications.

:::tip Why use React props over raw Bulma classes?

- **TypeScript catches typos at compile time.** `color="primery"` fails to build; `class="is-primery"` silently renders a broken button.
- **IDE autocomplete** for every component, prop, and allowed value — no memorizing Bulma's class vocabulary.
- **Enumerated values.** `size` only accepts `'small' | 'normal' | 'medium' | 'large'`. Illegal combinations don't type-check.
- **Discoverable API.** Hover or Cmd-click a prop to jump to its definition. Classes are opaque strings.
- **Refactor-safe.** Renaming a prop is a codemod; renaming across class-string literals is fragile.
- **One source of truth.** Each prop → class mapping lives in one place, so upgrades propagate to every component.
  :::

### Property to Class Conversion

Instead of writing class names manually, you use React props.

Instead of this HTML:

```html
<button class="button is-primary is-large is-rounded is-loading">
  Loading
</button>
```

You write this React:

```tsx live
<Button color="primary" size="large" rounded loading>
  Loading
</Button>
```

### Helper Classes Integration

The library integrates with Bulma's helper classes through the `useBulmaClasses` hook. You can apply spacing, colors, typography, and other utilities directly as props:

```tsx live
<>
  <Block>
    Typography and spacing helpers
    <Button color="primary" textSize="5" textWeight="bold" m="4" p="2">
      Styled Button
    </Button>
  </Block>

  <Block>
    Flexbox helpers
    <Box
      display="flex"
      justifyContent="center"
      alignItems="center"
      backgroundColor="dark"
      p="5"
    >
      <Button color="primary">Centered Button</Button>
    </Box>
  </Block>
</>
```

### Property Types and Mappings

#### Color and Background Color

Color properties map to Bulma's text and background color classes:

```tsx live
<>
  <Block>
    <Title>Text colors</Title>
    <Box>
      <Title color="primary">Primary text → has-text-primary</Title>
      <Title color="grey-dark">Dark grey text → has-text-grey-dark</Title>
    </Box>
  </Block>

  <Block>
    <Title>Background colors</Title>
    <Box backgroundColor="info" color="dark">
      Info background → has-background-info
    </Box>
    <Box backgroundColor="light" color="dark">
      Light background → has-background-light
    </Box>
  </Block>
</>
```

#### Spacing

Spacing properties use Bulma's spacing scale (0-6):

```tsx live
<>
  <Box m="4">All margins → m-4</Box>
  <Box mt="2" mb="3">
    Top/bottom → mt-2 mb-3
  </Box>
  <Box mx="auto">Centered → mx-auto</Box>
  <Box p="5">All padding → p-5</Box>
  <Box px="3" py="2">
    Horizontal/vertical → px-3 py-2
  </Box>
</>
```

#### Typography

Typography properties control text appearance:

```tsx live
<>
  <Box>
    <Title textSize="1" textAlign="centered" textWeight="bold">
      Large Centered Title
    </Title>
    → is-size-1 has-text-centered has-text-weight-bold

    <Content textTransform="uppercase" fontFamily="monospace">
      Uppercase monospace content → is-uppercase is-family-monospace
    </Content>
  </Box>
</>
```

#### Visibility and Display

Control element visibility and display behavior:

```tsx live
<>
  <Block>
    <Title>Display utilities</Title>
    <Box display="flex">Flexbox container → is-flex</Box>
    <Box display="inline-block">Inline block → is-inline-block</Box>
  </Block>

  <Block>
    <Title>Visibility utilities</Title>
    The box below does not appear, it is hidden
    <Box visibility="hidden">Hidden content → is-hidden</Box>
    The box below does not appear, it is present for screen readers
    <Box visibility="sr-only">Screen reader only → is-sr-only</Box>
  </Block>
</>
```

#### Flexbox

Flexbox properties provide layout control:

```tsx live
<>
  <Box
    display="flex"
    flexDirection="column"
    justifyContent="space-between"
    alignItems="center"
  >
    <Content>
      → is-flex is-flex-direction-column is-justify-content-space-between
      is-align-items-center
    </Content>
    <Buttons>
      <Button>Top</Button>
      <Button>Bottom</Button>
    </Buttons>
  </Box>
</>
```

:::info

display="flex" → is-flex

flexDirection="column" → is-flex-direction-column

justifyContent="space-between" → is-justify-content-space-between

alignItems="center" → is-align-items-center

:::

#### Other Utilities

Additional helper properties for common use cases:

```tsx live
<>
  <Block>
    Float utilities
    <Box float="left">Float left → is-pulled-left</Box>
    <Box float="right">Float right → is-pulled-right</Box>
  </Block>

  <Block>
    Overflow control
    <Box overflow="clipped">Clipped overflow → is-clipped</Box>
  </Block>

  <Block>
    Radius and Shadow
    <Box radius="radiusless">No radius → is-radiusless</Box>
    <Box shadow="shadowless">No shadow → is-shadowless</Box>
  </Block>

  <Block>
    Interactive states 
    <Box interaction="unselectable">No select → is-unselectable</Box>
    <Box interaction="clickable">Clickable → is-clickable</Box>
  </Block>
</>
```

### Responsive Properties

The `useBulmaClasses` hook provides **two ways** to apply responsive styles:

#### 1. Global Viewport Property (Legacy)

Use the `viewport` prop to apply a single viewport modifier to ALL properties that support it:

:::tip Test Responsive Behavior

Try resizing your browser window or using the responsive design mode in your browser's developer tools. The text alignment in the example below should be **right-aligned on mobile** (up to 768px width) but **left-aligned on tablet and larger** viewports.

:::

```tsx live
<Box textAlign="right" viewport="mobile" m="2">
  Mobile-specific styling → has-text-right-mobile
</Box>
```

#### 2. Viewport-Specific Properties (Recommended)

Use individual viewport properties to set **different values for each viewport**:

:::tip Test Viewport-Specific Properties

To see the responsive behavior in the example below, resize your browser window or use your browser's responsive design mode (F12 → Device Toolbar). Try these specific viewport widths:

- **Mobile**: 320px - 768px (text will be size 6, right-aligned)
- **Tablet**: 769px - 1023px (text will be size 3, left-aligned, and hidden on desktop!)
- **Desktop**: 1024px+ (element will be hidden)

:::

```tsx live
<>
  <Block>
    <Box
      textSizeMobile="6"
      textSizeTablet="3"
      textAlignMobile="right"
      textAlignTablet="left"
      visibilityDesktop="hidden"
      p="3"
    >
      This box demonstrates viewport-specific properties: different text sizes,
      alignment, and visibility per viewport. (Hidden on tablet!)
    </Box>
  </Block>
</>
```

Available breakpoints:

- `mobile`: up to 768px
- `tablet`: from 769px
- `desktop`: from 1024px
- `widescreen`: from 1216px
- `fullhd`: from 1408px

:::info Responsive Support

**Global Viewport Property** works with these properties:

- **Typography**: `textSize`, `textAlign`
- **Display**: `display`
- **Visibility**: `visibility` (only for `hidden`, not `sr-only`)

**Viewport-Specific Properties** available:

- **Text Size**: `textSizeMobile`, `textSizeTablet`, `textSizeDesktop`, `textSizeWidescreen`, `textSizeFullhd`
- **Text Alignment**: `textAlignMobile`, `textAlignTablet`, `textAlignDesktop`, `textAlignWidescreen`, `textAlignFullhd`
- **Visibility**: `visibilityMobile`, `visibilityTablet`, `visibilityDesktop`, `visibilityWidescreen`, `visibilityFullhd`
- **Display**: `displayMobile`, `displayTablet`, `displayDesktop`, `displayWidescreen`, `displayFullhd`

**Note**: The following properties do **not** support responsive variants in Bulma:

- **Text and Background Colors** (`color`, `backgroundColor`) - These classes do not exist in Bulma
- Spacing (`m`, `p`, `mt`, `mb`, etc.)
- Color shades (when `colorShade` is specified)
- Flexbox properties
- Most other helper classes

:::

### Component-Specific Properties

In addition to helper classes, each component has its own specific properties that map to Bulma modifiers:

```tsx live
<>
  <Block>
    Button-specific properties
    <Button color="primary" size="large" outlined rounded loading>
      Button Text
    </Button>
  </Block>

  <Block>
    <Field label="Input-specific properties">
      <Control>
        <Input
          type="email"
          placeholder="Email"
          color="success"
          size="medium"
          rounded
        />
      </Control>
    </Field>
  </Block>

  <Block>
    Column-specific properties
    <Column size="half" offset="one-quarter">
      <Notification color="primary">Column Content</Notification>
    </Column>
  </Block>
</>
```

**Component-Specific Properties in the examples above:**

- **Button**: `size`, `outlined`, `rounded`, `loading` (these are not available in `useBulmaClasses`)
- **Input**: `type`, `placeholder`, `size`, `rounded` (form-specific properties)
- **Column**: `size`, `offset` (grid layout properties)
- **Field**: `label` (form field property)

These properties are unique to each component and directly map to Bulma's component-specific modifier classes. For example, `<Button size="large" />` generates `class="button is-large"`.

:::info Component API Documentation

Each component has many additional specific properties beyond what's shown here. For a complete list of all available properties for any component, refer to the **API Documentation** section where each component's props, examples, and Bulma class mappings are thoroughly documented.

:::

## Advanced Usage

For more complex scenarios, you can combine the helper props with your own CSS classes:

```tsx live
<Button
  color="primary"
  className="my-custom-button"
  textSize="4"
  m="3"
  display="flex"
  alignItems="center"
>
  <Icon name="star" mr="2" />
  Custom Styled Button
</Button>
```

:::note `className` is for _your_ CSS, not Bulma's
Use `className` for app-specific classes defined in your own stylesheets (like `my-custom-button` above). Don't reach for `className="is-primary"` as an escape hatch for Bulma modifiers — if a Bulma class isn't exposed through a prop, open an issue so we can add it. This keeps your call sites type-safe.
:::

## Further Reading

This guide covers the essential syntax concepts. For comprehensive details about all available helper properties and their mappings, see the [useBulmaClasses documentation](../../api/helpers/usebulmaclasses.md).

---

## CSS Variations


Bestax ships pre-built CSS variations that combine Bulma with bestax extras into a single file. Each variation mirrors a Bulma variation but includes all bestax extra component styles, so you only need one CSS import.

---

## Complete (Recommended)

The full bestax CSS including Bulma, all extras, helpers, and dark mode support. **This is the recommended version for most projects.**

**Prefix:** None\
**Import Statement:**

```js

```

**Usage:**

```tsx live

function App() {
  return (
    <Box>
      <Title>Complete Bestax</Title>
      <Button color="primary">Primary Button</Button>
    </Box>
  );
}
```

---

## Prefixed (`bestax-`)

All CSS classes are prefixed with `bestax-` to avoid conflicts with other CSS frameworks.

**Prefix:** `bestax-`\
**Import Statement:**

```js

```

**Usage:**

```tsx live

function App() {
  return (
    <ConfigProvider classPrefix="bestax-">
      <Box>
        <Title size={2}>Bestax-Prefixed Components</Title>
        
          All components inside this ConfigProvider will have their CSS classes
          prefixed with "bestax-". This allows you to use bestax alongside other
          CSS frameworks without class name conflicts.
        
        <Button color="primary" mt="3">
          Bestax-Prefixed Button
        </Button>
      </Box>
    </ConfigProvider>
  );
}
```

This renders HTML with prefixed classes:

```html title="HTML markup from example above"

  Bestax-Prefixed Components
  <button class="bestax-button bestax-is-primary">
    Bestax-Prefixed Button
  </button>

```

---

## No Helpers

Includes Bulma core components and bestax extras, but excludes Bulma helper classes (spacing, typography, color utilities, etc.).

**Prefix:** None\
**Import Statement:**

```js

```

**Usage:**

```tsx

function App() {
  return (
    <Box>
      <Title>No Helpers</Title>
      <Button color="primary">Primary Button</Button>
      {/* Helper classes like 'has-text-centered', 'mt-4', etc. won't work */}
    </Box>
  );
}
```

:::warning
Without helper classes, you'll need to use custom CSS for spacing, text alignment, and other utilities that are normally provided by Bulma helpers.
:::

---

## No Helpers, Prefixed

Combines the no-helpers version with the `bestax-` class prefix. Smallest prefixed bundle.

**Prefix:** `bestax-`\
**Import Statement:**

```js

```

**Usage:**

```tsx

function App() {
  return (
    <ConfigProvider classPrefix="bestax-">
      <Box>
        <Title>No Helpers, Prefixed</Title>
        <Button color="primary">Primary Button</Button>
      </Box>
    </ConfigProvider>
  );
}
```

---

## No Dark Mode

Includes everything except dark mode styles, resulting in a smaller file size. Only the light theme is applied.

**Prefix:** None\
**Import Statement:**

```js

```

**Usage:**

```tsx

function App() {
  return (
    <Box>
      <Title>Light Mode Only</Title>
      <Button color="primary">Primary Button</Button>
      {/* Dark mode styles are not included */}
    </Box>
  );
}
```

:::info
This version is ideal for applications that only support light mode and want to minimize CSS bundle size.
:::

---

## Custom Brand (SCSS Only)

For teams that want a custom class prefix matching their brand or organization. This requires building from SCSS source.

**Prefix:** Custom (e.g., `mycompany-`)\
**Setup:**

1. **Install dependencies:**

   ```bash
   pnpm add bulma sass
   ```

2. **Create a custom SCSS file:**

   ```scss title="src/styles/mycompany-bestax.scss"
   @use 'bulma/sass' with (
     $class-prefix: 'mycompany-'
   );

   // Include bestax extras (Toast, Dialog, Carousel, Slider, Switch, etc.)
   @use '@allxsmith/bestax-bulma/scss';
   ```

3. **Import the custom SCSS file:**

   ```js title="src/index.js"

   ```

**Usage:**

```tsx

function App() {
  return (
    <ConfigProvider classPrefix="mycompany-">
      <Box>
        <Title>Custom Brand Prefix</Title>
        <Button color="primary">Branded Button</Button>
      </Box>
    </ConfigProvider>
  );
}
```

This approach allows you to:

- Use your own brand prefix across all Bulma and bestax classes
- Customize Bulma variables during the build process
- Maintain consistency with your design system naming conventions

---

## Choosing the Right Variation

| Use Case                                  | Recommended Variation                                   |
| ----------------------------------------- | ------------------------------------------------------- |
| **New project, full control**             | Complete (`bestax.css`)                                 |
| **Avoid class conflicts (bestax prefix)** | Prefixed (`bestax-prefixed.css`)                        |
| **Custom styling, minimal CSS**           | No Helpers (`bestax-no-helpers.css`)                    |
| **Minimal CSS + prefixed**                | No Helpers, Prefixed (`bestax-no-helpers-prefixed.css`) |
| **Light mode only, smaller bundle**       | No Dark Mode (`bestax-no-dark-mode.css`)                |
| **Enterprise/branded applications**       | Custom Brand (custom SCSS build)                        |

---

## File Size Comparison

| Variation            | Gzipped Size | Description                      |
| -------------------- | ------------ | -------------------------------- |
| Complete             | ~78KB        | Full-featured, recommended       |
| Prefixed (`bestax-`) | ~80KB        | Full + `bestax-` class prefix    |
| No Helpers           | ~63KB        | No helper utilities              |
| No Helpers, Prefixed | ~64KB        | No helpers + `bestax-` prefix    |
| No Dark Mode         | ~66KB        | Light theme only                 |
| Custom Brand         | ~78KB        | Custom prefix, built from source |

:::tip
All sizes are approximate gzipped transfer sizes. Enable gzip compression on your server to achieve these transfer sizes.
:::

---

## Next Steps

- **Learn about configuration options**: [ConfigProvider](/docs/api/helpers/config)
- **Explore theming capabilities**: [Theme](/docs/api/helpers/theme)
- **Alternative icon libraries**: [Alternative Icons](/docs/guides/getting-started/alternative-icons)
- **Framework-specific setup**: [React Setups](/docs/guides/getting-started/react-setups)
- **Browse all components**: [API Documentation](/docs/category/elements)

---

## Color Shades


Bulma v1 introduces an extended color palette system that provides semantic color variations beyond the basic color helpers. These palette helpers give you access to a comprehensive range of color shades and semantic meanings for each color.

Bestax-bulma refers to the color palette as **Color Shades** `colorShades`.

:::tip Composable hook

These props are also available standalone via the `useColorClasses` hook (the same hook covers both colors and shades) — see [Composable Mini-Hooks](/docs/api/helpers/usebulmaclasses#composable-mini-hooks).

:::

:::info Reference

This page documents the bestax-bulma prop API for Bulma's palette helpers. For the underlying CSS utilities, see the [official Bulma palette helpers](https://bulma.io/documentation/helpers/palette-helpers/).

:::

:::info

The color palette system is built on CSS variables, allowing for runtime customization and dynamic theming. All palette colors work seamlessly with the [Theme component](/docs/api/helpers/theme) for advanced theming scenarios.

:::

## Available Shades

:::info

Bulma v1 introduces comprehensive color shades using CSS variables. You can combine the `color` prop with the `colorShade` prop for text colors, and the `backgroundColor` prop with the `backgroundColorShade` prop for background colors to access different variations of each color.

:::

### Numeric Shades (00-95)

**Text Color Shades:**

| Property          | Bulma Class Suffix | Description              |
| ----------------- | ------------------ | ------------------------ |
| `colorShade="00"` | `-00`              | Lightest shade (0%)      |
| `colorShade="05"` | `-05`              | Very light shade (5%)    |
| `colorShade="10"` | `-10`              | Light shade (10%)        |
| `colorShade="15"` | `-15`              | Light shade (15%)        |
| `colorShade="20"` | `-20`              | Light shade (20%)        |
| `colorShade="25"` | `-25`              | Light shade (25%)        |
| `colorShade="30"` | `-30`              | Light shade (30%)        |
| `colorShade="35"` | `-35`              | Light shade (35%)        |
| `colorShade="40"` | `-40`              | Medium light shade (40%) |
| `colorShade="45"` | `-45`              | Medium light shade (45%) |
| `colorShade="50"` | `-50`              | Medium shade (50%)       |
| `colorShade="55"` | `-55`              | Medium shade (55%)       |
| `colorShade="60"` | `-60`              | Medium dark shade (60%)  |
| `colorShade="65"` | `-65`              | Medium dark shade (65%)  |
| `colorShade="70"` | `-70`              | Dark shade (70%)         |
| `colorShade="75"` | `-75`              | Dark shade (75%)         |
| `colorShade="80"` | `-80`              | Dark shade (80%)         |
| `colorShade="85"` | `-85`              | Dark shade (85%)         |
| `colorShade="90"` | `-90`              | Very dark shade (90%)    |
| `colorShade="95"` | `-95`              | Darkest shade (95%)      |

**Background Color Shades:**

| Property                    | Bulma Class Suffix | Description              |
| --------------------------- | ------------------ | ------------------------ |
| `backgroundColorShade="00"` | `-00`              | Lightest shade (0%)      |
| `backgroundColorShade="05"` | `-05`              | Very light shade (5%)    |
| `backgroundColorShade="10"` | `-10`              | Light shade (10%)        |
| `backgroundColorShade="15"` | `-15`              | Light shade (15%)        |
| `backgroundColorShade="20"` | `-20`              | Light shade (20%)        |
| `backgroundColorShade="25"` | `-25`              | Light shade (25%)        |
| `backgroundColorShade="30"` | `-30`              | Light shade (30%)        |
| `backgroundColorShade="35"` | `-35`              | Light shade (35%)        |
| `backgroundColorShade="40"` | `-40`              | Medium light shade (40%) |
| `backgroundColorShade="45"` | `-45`              | Medium light shade (45%) |
| `backgroundColorShade="50"` | `-50`              | Medium shade (50%)       |
| `backgroundColorShade="55"` | `-55`              | Medium shade (55%)       |
| `backgroundColorShade="60"` | `-60`              | Medium dark shade (60%)  |
| `backgroundColorShade="65"` | `-65`              | Medium dark shade (65%)  |
| `backgroundColorShade="70"` | `-70`              | Dark shade (70%)         |
| `backgroundColorShade="75"` | `-75`              | Dark shade (75%)         |
| `backgroundColorShade="80"` | `-80`              | Dark shade (80%)         |
| `backgroundColorShade="85"` | `-85`              | Dark shade (85%)         |
| `backgroundColorShade="90"` | `-90`              | Very dark shade (90%)    |
| `backgroundColorShade="95"` | `-95`              | Darkest shade (95%)      |

### Semantic Shades

**Text Color Shades:**

| Property                 | Bulma Class Suffix | Description                  |
| ------------------------ | ------------------ | ---------------------------- |
| `colorShade="invert"`    | `-invert`          | Inverted color               |
| `colorShade="light"`     | `-light`           | Light variant                |
| `colorShade="dark"`      | `-dark`            | Dark variant                 |
| `colorShade="soft"`      | `-soft`            | Soft variant                 |
| `colorShade="bold"`      | `-bold`            | Bold variant                 |
| `colorShade="on-scheme"` | `-on-scheme`       | Contrasting color for scheme |

**Background Color Shades:**

| Property                           | Bulma Class Suffix | Description                  |
| ---------------------------------- | ------------------ | ---------------------------- |
| `backgroundColorShade="invert"`    | `-invert`          | Inverted color               |
| `backgroundColorShade="light"`     | `-light`           | Light variant                |
| `backgroundColorShade="dark"`      | `-dark`            | Dark variant                 |
| `backgroundColorShade="soft"`      | `-soft`            | Soft variant                 |
| `backgroundColorShade="bold"`      | `-bold`            | Bold variant                 |
| `backgroundColorShade="on-scheme"` | `-on-scheme`       | Contrasting color for scheme |

### Basic Shade Usage Example

```tsx live

function ColorShadeExamples() {
  return (
    <Box p="4">
      {/* Text color shades */}
      <Title color="primary" colorShade="30" mb="3">
        Primary 30% shade title
      </Title>

      {/* Background color shades */}
      <Box
        backgroundColor="info"
        backgroundColorShade="10"
        color="dark"
        p="3"
        mb="3"
      >
        Light info background (10%)
      </Box>

      <Box
        backgroundColor="success"
        backgroundColorShade="70"
        color="white"
        p="3"
        mb="3"
      >
        Dark success background (70%)
      </Box>

      {/* Button variations */}
      
        <Button color="danger" colorShade="light" mr="2">
          Light danger
        </Button>
        <Button color="warning" colorShade="dark" mr="2">
          Dark warning
        </Button>
        <Button color="primary" colorShade="invert">
          Inverted primary
        </Button>
      

      {/* Tag variations */}
      
        <Tag color="info" colorShade="25" mr="2">
          25% Info
        </Tag>
        <Tag color="success" colorShade="50" mr="2">
          50% Success
        </Tag>
        <Tag color="warning" colorShade="75">
          75% Warning
        </Tag>
      
    </Box>
  );
}
```

## Bulma Primary Colors

The primary color palette includes all the main Bulma colors with their full range of variations. Each color has multiple shades available through the palette system.

### Applying Numeric Shades to Primary Colors

You can apply any numeric shade (00-95) to any primary color by combining the `color` or `backgroundColor` prop with the appropriate shade prop:

- For text colors: use `color` + `colorShade`
- For background colors: use `backgroundColor` + `backgroundColorShade`

```tsx live

function PrimaryColorShades() {
  return (
    <Box p="4">
      {/* Primary text color with numeric shades */}
      <Title color="primary" colorShade="20" size="4" mb="3">
        Primary 20% - Very Light
      </Title>
      <Title color="primary" colorShade="50" size="4" mb="3">
        Primary 50% - Medium
      </Title>
      <Title color="primary" colorShade="80" size="4" mb="3">
        Primary 80% - Dark
      </Title>

      {/* Background variations */}
      <Box
        backgroundColor="primary"
        backgroundColorShade="10"
        color="dark"
        p="3"
        mb="2"
      >
        Primary 10% Background
      </Box>
      <Box
        backgroundColor="primary"
        backgroundColorShade="30"
        p="3"
        mb="2"
        color="white"
      >
        Primary 30% Background
      </Box>
      <Box
        backgroundColor="primary"
        backgroundColorShade="60"
        p="3"
        mb="2"
        color="white"
      >
        Primary 60% Background
      </Box>
      <Box
        backgroundColor="primary"
        backgroundColorShade="90"
        p="3"
        mb="4"
        color="white"
      >
        Primary 90% Background
      </Box>

      {/* Button progression */}
      
        <Button
          backgroundColor="primary"
          backgroundColorShade="15"
          color="primary"
          mr="2"
        >
          15%
        </Button>
        <Button
          backgroundColor="primary"
          backgroundColorShade="35"
          color="white"
          mr="2"
        >
          35%
        </Button>
        <Button
          backgroundColor="primary"
          backgroundColorShade="55"
          color="white"
          mr="2"
        >
          55%
        </Button>
        <Button
          backgroundColor="primary"
          backgroundColorShade="75"
          color="white"
          mr="2"
        >
          75%
        </Button>
        <Button
          backgroundColor="primary"
          backgroundColorShade="95"
          color="white"
        >
          95%
        </Button>
      
    </Box>
  );
}
```

### All Colors Support Numeric Shades

Every Bulma color supports the full range of numeric shades:

```tsx live

function AllColorShades() {
  return (
    <Box p="4">
      {/* Success shades */}
      
        <Tag
          backgroundColor="success"
          backgroundColorShade="20"
          color="success"
          mr="2"
        >
          Success 20%
        </Tag>
        <Tag
          backgroundColor="success"
          backgroundColorShade="40"
          color="white"
          mr="2"
        >
          Success 40%
        </Tag>
        <Tag
          backgroundColor="success"
          backgroundColorShade="60"
          color="white"
          mr="2"
        >
          Success 60%
        </Tag>
        <Tag backgroundColor="success" backgroundColorShade="80" color="white">
          Success 80%
        </Tag>
      

      {/* Info shades */}
      
        <Tag
          backgroundColor="info"
          backgroundColorShade="25"
          color="info"
          mr="2"
        >
          Info 25%
        </Tag>
        <Tag
          backgroundColor="info"
          backgroundColorShade="45"
          color="white"
          mr="2"
        >
          Info 45%
        </Tag>
        <Tag
          backgroundColor="info"
          backgroundColorShade="65"
          color="white"
          mr="2"
        >
          Info 65%
        </Tag>
        <Tag backgroundColor="info" backgroundColorShade="85" color="white">
          Info 85%
        </Tag>
      

      {/* Warning shades */}
      
        <Tag
          backgroundColor="warning"
          backgroundColorShade="30"
          color="warning"
          mr="2"
        >
          Warning 30%
        </Tag>
        <Tag
          backgroundColor="warning"
          backgroundColorShade="50"
          color="white"
          mr="2"
        >
          Warning 50%
        </Tag>
        <Tag
          backgroundColor="warning"
          backgroundColorShade="70"
          color="white"
          mr="2"
        >
          Warning 70%
        </Tag>
        <Tag backgroundColor="warning" backgroundColorShade="90" color="white">
          Warning 90%
        </Tag>
      

      {/* Danger shades */}
      
        <Tag
          backgroundColor="danger"
          backgroundColorShade="35"
          color="danger"
          mr="2"
        >
          Danger 35%
        </Tag>
        <Tag
          backgroundColor="danger"
          backgroundColorShade="55"
          color="white"
          mr="2"
        >
          Danger 55%
        </Tag>
        <Tag
          backgroundColor="danger"
          backgroundColorShade="75"
          color="white"
          mr="2"
        >
          Danger 75%
        </Tag>
        <Tag backgroundColor="danger" backgroundColorShade="95" color="white">
          Danger 95%
        </Tag>
      
    </Box>
  );
}
```

### Primary Color Variations

| Property                                 | Bulma Class                  | Description                                    |
| ---------------------------------------- | ---------------------------- | ---------------------------------------------- |
| `color="primary"`                        | `has-text-primary`           | Base primary color                             |
| `color="primary" colorShade="light"`     | `has-text-primary-light`     | Light primary variant                          |
| `color="primary" colorShade="dark"`      | `has-text-primary-dark`      | Dark primary variant                           |
| `color="primary" colorShade="soft"`      | `has-text-primary-soft`      | Soft primary variant                           |
| `color="primary" colorShade="bold"`      | `has-text-primary-bold`      | Bold primary variant                           |
| `color="primary" colorShade="on-scheme"` | `has-text-primary-on-scheme` | Primary color optimized for scheme backgrounds |
| `color="primary" colorShade="00"`        | `has-text-primary-00`        | Primary 0% shade (lightest)                    |
| `color="primary" colorShade="25"`        | `has-text-primary-25`        | Primary 25% shade                              |
| `color="primary" colorShade="50"`        | `has-text-primary-50`        | Primary 50% shade                              |
| `color="primary" colorShade="75"`        | `has-text-primary-75`        | Primary 75% shade                              |
| `color="primary" colorShade="95"`        | `has-text-primary-95`        | Primary 95% shade (darkest)                    |

### Link Color Variations

| Property                          | Bulma Class           | Description        |
| --------------------------------- | --------------------- | ------------------ |
| `color="link"`                    | `has-text-link`       | Base link color    |
| `color="link" colorShade="light"` | `has-text-link-light` | Light link variant |
| `color="link" colorShade="dark"`  | `has-text-link-dark`  | Dark link variant  |
| `color="link" colorShade="soft"`  | `has-text-link-soft`  | Soft link variant  |
| `color="link" colorShade="bold"`  | `has-text-link-bold`  | Bold link variant  |

### Info Color Variations

| Property                          | Bulma Class           | Description        |
| --------------------------------- | --------------------- | ------------------ |
| `color="info"`                    | `has-text-info`       | Base info color    |
| `color="info" colorShade="light"` | `has-text-info-light` | Light info variant |
| `color="info" colorShade="dark"`  | `has-text-info-dark`  | Dark info variant  |
| `color="info" colorShade="soft"`  | `has-text-info-soft`  | Soft info variant  |
| `color="info" colorShade="bold"`  | `has-text-info-bold`  | Bold info variant  |

### Success Color Variations

| Property                             | Bulma Class              | Description           |
| ------------------------------------ | ------------------------ | --------------------- |
| `color="success"`                    | `has-text-success`       | Base success color    |
| `color="success" colorShade="light"` | `has-text-success-light` | Light success variant |
| `color="success" colorShade="dark"`  | `has-text-success-dark`  | Dark success variant  |
| `color="success" colorShade="soft"`  | `has-text-success-soft`  | Soft success variant  |
| `color="success" colorShade="bold"`  | `has-text-success-bold`  | Bold success variant  |

### Warning Color Variations

| Property                             | Bulma Class              | Description           |
| ------------------------------------ | ------------------------ | --------------------- |
| `color="warning"`                    | `has-text-warning`       | Base warning color    |
| `color="warning" colorShade="light"` | `has-text-warning-light` | Light warning variant |
| `color="warning" colorShade="dark"`  | `has-text-warning-dark`  | Dark warning variant  |
| `color="warning" colorShade="soft"`  | `has-text-warning-soft`  | Soft warning variant  |
| `color="warning" colorShade="bold"`  | `has-text-warning-bold`  | Bold warning variant  |

### Danger Color Variations

| Property                            | Bulma Class             | Description          |
| ----------------------------------- | ----------------------- | -------------------- |
| `color="danger"`                    | `has-text-danger`       | Base danger color    |
| `color="danger" colorShade="light"` | `has-text-danger-light` | Light danger variant |
| `color="danger" colorShade="dark"`  | `has-text-danger-dark`  | Dark danger variant  |
| `color="danger" colorShade="soft"`  | `has-text-danger-soft`  | Soft danger variant  |
| `color="danger" colorShade="bold"`  | `has-text-danger-bold`  | Bold danger variant  |

## Text Color

Apply palette text colors using the `color` and `colorShade` props together. This provides semantic meaning while maintaining visual consistency.

### Example Usage

```tsx live

function PaletteTextExample() {
  return (
    <Box p="4">
      <Title color="primary" colorShade="bold" size="2" mb="3">
        Bold Primary Heading
      </Title>

      <SubTitle color="info" colorShade="soft" size="4" mb="4">
        Soft Info Subheading
      </SubTitle>

      <Content>
        
          
            Success message
          {' '}
          - Operation completed successfully.
        
        
          
            Warning notice
          {' '}
          - Please review before proceeding.
        
        
          
            Error message
          {' '}
          - Something went wrong.
        
      </Content>
    </Box>
  );
}
```

## Background Color

Apply palette background colors using the `backgroundColor` and `backgroundColorShade` props together. This creates sophisticated color schemes with semantic meaning.

### Primary Background Variations

| Property                                                 | Bulma Class                    | Description              |
| -------------------------------------------------------- | ------------------------------ | ------------------------ |
| `backgroundColor="primary"`                              | `has-background-primary`       | Base primary background  |
| `backgroundColor="primary" backgroundColorShade="light"` | `has-background-primary-light` | Light primary background |
| `backgroundColor="primary" backgroundColorShade="dark"`  | `has-background-primary-dark`  | Dark primary background  |
| `backgroundColor="primary" backgroundColorShade="soft"`  | `has-background-primary-soft`  | Soft primary background  |
| `backgroundColor="primary" backgroundColorShade="bold"`  | `has-background-primary-bold`  | Bold primary background  |

### Status Background Variations

| Property                                                 | Bulma Class                    | Description              |
| -------------------------------------------------------- | ------------------------------ | ------------------------ |
| `backgroundColor="success" backgroundColorShade="light"` | `has-background-success-light` | Light success background |
| `backgroundColor="info" backgroundColorShade="soft"`     | `has-background-info-soft`     | Soft info background     |
| `backgroundColor="warning" backgroundColorShade="light"` | `has-background-warning-light` | Light warning background |
| `backgroundColor="danger" backgroundColorShade="soft"`   | `has-background-danger-soft`   | Soft danger background   |

### Example Usage

```tsx live

function PaletteBackgroundExample() {
  return (
    
      <Notification
        backgroundColor="success"
        backgroundColorShade="light"
        color="success"
        className="mb-4"
      >
        Success! Your changes have been saved.
      </Notification>

      <Notification
        backgroundColor="info"
        backgroundColorShade="soft"
        color="info"
        colorShade="dark"
        className="mb-4"
      >
        Info: System maintenance scheduled.
      </Notification>

      <Card
        backgroundColor="warning"
        backgroundColorShade="light"
        className="mb-4"
      >
        <Card.Content>
          <Title color="warning" colorShade="dark" size="5">
            Warning Notice
          </Title>
          <Content color="warning" colorShade="bold">
            Please backup your data before proceeding.
          </Content>
        </Card.Content>
      </Card>

      <Message backgroundColor="danger" backgroundColorShade="soft">
        <Message.Header backgroundColor="danger" color="white">
          Example Error Message
        </Message.Header>
        <Message.Body color="danger" colorShade="dark">
          This is an example of how error messages would appear using danger
          color shades.
        </Message.Body>
      </Message>
    
  );
}
```

## Numeric Shade Variations

:::tip

In addition to semantic shade names (light, dark, soft, bold), you can use numeric shades from 00 to 95 for precise color control.

:::

### Numeric Shade Examples

```tsx live

function NumericShadeExample() {
  return (
    <Box p="4">
      {/* Primary color progression */}
      
        <Title size="5" mb="3">
          Primary Color Progression
        </Title>
        <Box backgroundColor="primary" backgroundColorShade="10" p="2" mb="2">
          Primary 10% - Very light
        </Box>
        <Box backgroundColor="primary" backgroundColorShade="25" p="2" mb="2">
          Primary 25% - Light
        </Box>
        <Box
          backgroundColor="primary"
          backgroundColorShade="50"
          p="2"
          mb="2"
          color="dark"
        >
          Primary 50% - Medium
        </Box>
        <Box
          backgroundColor="primary"
          backgroundColorShade="75"
          p="2"
          mb="2"
          color="dark"
        >
          Primary 75% - Dark
        </Box>
        <Box
          backgroundColor="primary"
          backgroundColorShade="90"
          p="2"
          color="dark"
        >
          Primary 90% - Very dark
        </Box>
      

      {/* Button variations */}
      
        <Title size="5" mb="3">
          Button Variations
        </Title>
        <Button
          backgroundColor="info"
          backgroundColorShade="20"
          color="info"
          mr="2"
        >
          20% Info
        </Button>
        <Button
          backgroundColor="success"
          backgroundColorShade="40"
          color="white"
          mr="2"
        >
          40% Success
        </Button>
        <Button
          backgroundColor="warning"
          backgroundColorShade="60"
          color="white"
          mr="2"
        >
          60% Warning
        </Button>
        <Button
          backgroundColor="danger"
          backgroundColorShade="80"
          color="white"
        >
          80% Danger
        </Button>
      

      {/* Tag variations */}
      
        <Title size="5" mb="3">
          Tag Variations
        </Title>
        <Tag color="primary" colorShade="30" mr="2">
          30%
        </Tag>
        <Tag color="info" colorShade="45" mr="2">
          45%
        </Tag>
        <Tag color="success" colorShade="65" mr="2">
          65%
        </Tag>
        <Tag color="warning" colorShade="85">
          85%
        </Tag>
      
    </Box>
  );
}
```

## Advanced Palette Combinations

Create sophisticated designs by combining different aspects of the color palette:

```tsx live

function AdvancedPaletteExample() {
  return (
    <Box p="4">
      {/* Status cards with coordinated colors */}
      <Box display="flex" flexDirection="column" gap="4">
        {/* Success Card */}
        <Card backgroundColor="success" backgroundColorShade="05">
          <Card.Content>
            <Title color="success" colorShade="dark" size="5">
              Task Completed
            </Title>
            <Content color="success" colorShade="70">
              Your deployment was successful. All services are running normally.
            </Content>
            <Button
              backgroundColor="success"
              backgroundColorShade="bold"
              color="white"
              size="small"
            >
              View Details
            </Button>
          </Card.Content>
        </Card>

        {/* Info Card */}
        <Card backgroundColor="info" backgroundColorShade="10">
          <Card.Content>
            <Title color="info" colorShade="dark" size="5">
              System Update
            </Title>
            <Content color="info" colorShade="75">
              A new version is available. Update recommended for improved
              performance.
            </Content>
            <Button
              backgroundColor="info"
              backgroundColorShade="80"
              color="white"
              size="small"
            >
              Update Now
            </Button>
          </Card.Content>
        </Card>

        {/* Warning Card */}
        <Card backgroundColor="warning" backgroundColorShade="15">
          <Card.Content>
            <Title color="warning" colorShade="dark" size="5">
              Action Required
            </Title>
            <Content color="warning" colorShade="80">
              Your subscription will expire in 7 days. Please renew to continue
              service.
            </Content>
            <Button
              backgroundColor="warning"
              backgroundColorShade="bold"
              color="white"
              size="small"
            >
              Renew Now
            </Button>
          </Card.Content>
        </Card>
      </Box>
    </Box>
  );
}
```

## Theme Integration

:::info

Palette colors work seamlessly with the [Theme component](/docs/api/helpers/theme) for dynamic color schemes. You can override palette colors at runtime using CSS variables.

:::

```tsx live

function ThemedPaletteExample() {
  return (
    <Theme primaryH="270" primaryS="100%" primaryL="50%" isRoot>
      <Box p="4">
        <Title color="primary" colorShade="bold" mb="3">
          Custom Purple Theme
        </Title>

        <Box backgroundColor="primary" colorShade="10" p="3" mb="3">
          <Content color="primary" colorShade="dark">
            This uses the custom purple primary color with palette variations.
          </Content>
        </Box>

        <Button backgroundColor="primary" colorShade="60" color="white">
          Custom Primary Button
        </Button>
      </Box>
    </Theme>
  );
}
```

:::tip Learn More

For comprehensive information about color properties and shades, see the [useBulmaClasses API documentation](/docs/api/helpers/usebulmaclasses).

:::

## See Also

- [Color Helpers](/docs/guides/helpers/color) - Basic color system
- [CSS Variables](/docs/guides/features/css-variables) - Runtime color customization
- [Theme Component](/docs/api/helpers/theme) - Dynamic theming system
- [Configuration](/docs/guides/features/configuration) - Theme and color configuration
- [Bulma Palette Documentation](https://bulma.io/documentation/helpers/palette-helpers/) - Official Bulma palette helpers

---

## Color


Bulma provides a comprehensive set of color helpers for text and background colors. These helpers allow you to quickly apply consistent coloring throughout your application without writing custom CSS.

:::tip Composable hook

These props are also available standalone via the `useColorClasses` hook — see [Composable Mini-Hooks](/docs/api/helpers/usebulmaclasses#composable-mini-hooks).

:::

:::info Reference

This page documents the bestax-bulma prop API for Bulma's color helpers. For the underlying CSS utilities, see the [official Bulma color helpers](https://bulma.io/documentation/helpers/color-helpers/).

:::

:::tip

All components in bestax-bulma have access to these standard color properties through the `useBulmaClasses` hook. This means you can apply color properties to any component in the library.

:::

## Text Color

Use the `color` prop to apply text colors to any component. The color prop accepts Bulma's standard color palette.

### Standard Colors

| Property          | Bulma Class        | Color Value         |
| ----------------- | ------------------ | ------------------- |
| `color="primary"` | `has-text-primary` | Primary theme color |
| `color="link"`    | `has-text-link`    | Link color          |
| `color="info"`    | `has-text-info`    | Info blue           |
| `color="success"` | `has-text-success` | Success green       |
| `color="warning"` | `has-text-warning` | Warning yellow      |
| `color="danger"`  | `has-text-danger`  | Danger red          |

### Monochrome Colors

| Property               | Bulma Class             | Color Value   |
| ---------------------- | ----------------------- | ------------- |
| `color="black"`        | `has-text-black`        | Pure black    |
| `color="black-bis"`    | `has-text-black-bis`    | Almost black  |
| `color="black-ter"`    | `has-text-black-ter`    | Dark grey     |
| `color="grey-darker"`  | `has-text-grey-darker`  | Darker grey   |
| `color="grey-dark"`    | `has-text-grey-dark`    | Dark grey     |
| `color="grey"`         | `has-text-grey`         | Standard grey |
| `color="grey-light"`   | `has-text-grey-light`   | Light grey    |
| `color="grey-lighter"` | `has-text-grey-lighter` | Lighter grey  |
| `color="white"`        | `has-text-white`        | Pure white    |

### Theme Colors

| Property        | Bulma Class      | Color Value       |
| --------------- | ---------------- | ----------------- |
| `color="light"` | `has-text-light` | Light theme color |
| `color="dark"`  | `has-text-dark`  | Dark theme color  |

### Special Colors

| Property          | Bulma Class        | Color Value         |
| ----------------- | ------------------ | ------------------- |
| `color="inherit"` | `has-text-inherit` | Inherit from parent |
| `color="current"` | `has-text-current` | Current color value |

### Example Usage

```tsx live

function ColorExamples() {
  return (
    <Box p="4">
      <Title color="primary">Primary colored title</Title>
      <SubTitle color="info">Info colored subtitle</SubTitle>

      <Buttons>
        <Button color="success">Success button</Button>
        <Button color="warning">Warning button</Button>
        <Button color="danger">Danger button</Button>
      </Buttons>

      
        Grey text 
        Black text 
        White text
      
    </Box>
  );
}
```

## Background Color

Use the `backgroundColor` prop to apply background colors to any component. The backgroundColor prop accepts the same color values as the text color prop.

### Standard Background Colors

| Property                    | Bulma Class              | Background Value          |
| --------------------------- | ------------------------ | ------------------------- |
| `backgroundColor="primary"` | `has-background-primary` | Primary theme background  |
| `backgroundColor="link"`    | `has-background-link`    | Link background           |
| `backgroundColor="info"`    | `has-background-info`    | Info blue background      |
| `backgroundColor="success"` | `has-background-success` | Success green background  |
| `backgroundColor="warning"` | `has-background-warning` | Warning yellow background |
| `backgroundColor="danger"`  | `has-background-danger`  | Danger red background     |

### Monochrome Backgrounds

| Property                         | Bulma Class                   | Background Value         |
| -------------------------------- | ----------------------------- | ------------------------ |
| `backgroundColor="black"`        | `has-background-black`        | Black background         |
| `backgroundColor="black-bis"`    | `has-background-black-bis`    | Almost black background  |
| `backgroundColor="black-ter"`    | `has-background-black-ter`    | Dark grey background     |
| `backgroundColor="grey-darker"`  | `has-background-grey-darker`  | Darker grey background   |
| `backgroundColor="grey-dark"`    | `has-background-grey-dark`    | Dark grey background     |
| `backgroundColor="grey"`         | `has-background-grey`         | Standard grey background |
| `backgroundColor="grey-light"`   | `has-background-grey-light`   | Light grey background    |
| `backgroundColor="grey-lighter"` | `has-background-grey-lighter` | Lighter grey background  |
| `backgroundColor="white"`        | `has-background-white`        | White background         |

### Theme Backgrounds

| Property                  | Bulma Class            | Background Value       |
| ------------------------- | ---------------------- | ---------------------- |
| `backgroundColor="light"` | `has-background-light` | Light theme background |
| `backgroundColor="dark"`  | `has-background-dark`  | Dark theme background  |

### Special Backgrounds

| Property                    | Bulma Class              | Background Value    |
| --------------------------- | ------------------------ | ------------------- |
| `backgroundColor="inherit"` | `has-background-inherit` | Inherit from parent |
| `backgroundColor="current"` | `has-background-current` | Current color value |

### Example Usage

```tsx live

function BackgroundColorExamples() {
  return (
    
      <Box backgroundColor="primary" color="white" p="4" mb="3">
        Primary background with white text
      </Box>

      <Box backgroundColor="info" color="white" p="4" mb="3">
        Info background with white text
      </Box>

      <Notification backgroundColor="success" color="white">
        Success notification with custom colors
      </Notification>

      <Card backgroundColor="light" p="4">
        <Card.Content>Light background card</Card.Content>
      </Card>
    
  );
}
```

## Advanced Color Features

For more advanced color features including comprehensive shade variations and semantic color meanings, see the [Color Shades documentation](/docs/guides/helpers/color-palette).

:::tip Learn More

For detailed API information about color properties, see the [useBulmaClasses API documentation](/docs/api/helpers/usebulmaclasses).

:::

## See Also

- [Color Shades](/docs/guides/helpers/color-palette) - Extended color palette with numeric and semantic shades
- [CSS Variables](/docs/guides/features/css-variables) - Runtime color customization
- [Theme Component](/docs/api/helpers/theme) - Dynamic theming system
- [Bulma Color Documentation](https://bulma.io/documentation/helpers/color-helpers/) - Official Bulma color helpers

---

## Flex


Bulma provides comprehensive flexbox helpers that give you full control over flex container and flex item behavior. Combined with `display="flex"`, all of the flexbox CSS properties are available as helper classes in bestax-bulma.

:::tip Composable hook

These props are also available standalone via the `useFlexboxClasses` hook (container classes only emit when a `display` prop is `flex` or `inline-flex`) — see [Composable Mini-Hooks](/docs/api/helpers/usebulmaclasses#composable-mini-hooks).

:::

:::info Reference

This page documents the bestax-bulma prop API for Bulma's flexbox helpers. For the underlying CSS utilities, see the [official Bulma flexbox helpers](https://bulma.io/documentation/helpers/flexbox-helpers/).

:::

:::tip

All components in bestax-bulma have access to these flexbox properties through the `useBulmaClasses` hook. You can apply flexbox properties to any component in the library to create sophisticated responsive layouts.

:::

## Overview

Flexbox (Flexible Box Layout) is a powerful CSS layout method that allows you to arrange elements in a container with precise control over their alignment, direction, order, and size. Bulma's flexbox helpers cover all the essential flexbox properties:

- **flex-direction** - Controls the main axis direction
- **flex-wrap** - Controls whether items wrap to new lines
- **justify-content** - Aligns items along the main axis
- **align-content** - Aligns wrapped lines
- **align-items** - Aligns items along the cross axis
- **align-self** - Overrides align-items for individual items
- **flex-grow** - Controls how much an item should grow
- **flex-shrink** - Controls how much an item should shrink

## Flex Direction

The `flexDirection` prop controls the direction of the main axis in a flex container. This determines how flex items are laid out within the container.

| Property                         | Bulma Class                        | CSS Property                     |
| -------------------------------- | ---------------------------------- | -------------------------------- |
| `flexDirection="row"`            | `is-flex-direction-row`            | `flex-direction: row`            |
| `flexDirection="row-reverse"`    | `is-flex-direction-row-reverse`    | `flex-direction: row-reverse`    |
| `flexDirection="column"`         | `is-flex-direction-column`         | `flex-direction: column`         |
| `flexDirection="column-reverse"` | `is-flex-direction-column-reverse` | `flex-direction: column-reverse` |

### Flex Direction Examples

```tsx live

function FlexDirectionExamples() {
  return (
    <Box p="4">
      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Row Direction (Default)</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Box display="flex" flexDirection="row" backgroundColor="light" p="3">
            <Button color="primary" mr="2">
              Item 1
            </Button>
            <Button color="info" mr="2">
              Item 2
            </Button>
            <Button color="success">Item 3</Button>
          </Box>
        </Card.Content>
      </Card>

      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Row Reverse</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Box
            display="flex"
            flexDirection="row-reverse"
            backgroundColor="light"
            p="3"
          >
            <Button color="primary" ml="2">
              Item 1
            </Button>
            <Button color="info" ml="2">
              Item 2
            </Button>
            <Button color="success">Item 3</Button>
          </Box>
        </Card.Content>
      </Card>

      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Column Direction</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Box
            display="flex"
            flexDirection="column"
            backgroundColor="light"
            p="3"
          >
            <Button color="primary" mb="2">
              Item 1
            </Button>
            <Button color="info" mb="2">
              Item 2
            </Button>
            <Button color="success">Item 3</Button>
          </Box>
        </Card.Content>
      </Card>

      <Card>
        <Card.Header>
          <Card.Header.Title>Column Reverse</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Box
            display="flex"
            flexDirection="column-reverse"
            backgroundColor="light"
            p="3"
          >
            <Button color="primary" mt="2">
              Item 1
            </Button>
            <Button color="info" mt="2">
              Item 2
            </Button>
            <Button color="success">Item 3</Button>
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Flex Wrap

The `flexWrap` prop controls whether flex items wrap to new lines when they exceed the container width. This is essential for responsive layouts.

| Property                  | Bulma Class                 | CSS Property              |
| ------------------------- | --------------------------- | ------------------------- |
| `flexWrap="nowrap"`       | `is-flex-wrap-nowrap`       | `flex-wrap: nowrap`       |
| `flexWrap="wrap"`         | `is-flex-wrap-wrap`         | `flex-wrap: wrap`         |
| `flexWrap="wrap-reverse"` | `is-flex-wrap-wrap-reverse` | `flex-wrap: wrap-reverse` |

### Flex Wrap Examples

```tsx live

function FlexWrapExamples() {
  const tags = [
    'JavaScript',
    'TypeScript',
    'React',
    'Vue',
    'Angular',
    'Svelte',
    'Next.js',
    'Nuxt.js',
  ];

  return (
    <Box p="4">
      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>No Wrap (Default)</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content mb="3">
            Items overflow the container when they don't fit:
          </Content>
          :::tip Try This Resize your browser window to see the tags overflow
          horizontally when the container becomes too narrow. :::
          <Box display="flex" flexWrap="nowrap" backgroundColor="light" p="3">
            {tags.map((tag, index) => (
              <Tag key={index} color="info" mr="2">
                {tag}
              </Tag>
            ))}
          </Box>
        </Card.Content>
      </Card>

      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Wrap</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content mb="3">Items wrap to new lines when they don't fit:</Content>
          <Box display="flex" flexWrap="wrap" backgroundColor="light" p="3">
            {tags.map((tag, index) => (
              <Tag key={index} color="primary" mr="2" mb="2">
                {tag}
              </Tag>
            ))}
          </Box>
        </Card.Content>
      </Card>

      <Card>
        <Card.Header>
          <Card.Header.Title>Wrap Reverse</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content mb="3">Items wrap to new lines in reverse order:</Content>
          <Box
            display="flex"
            flexWrap="wrap-reverse"
            backgroundColor="light"
            p="3"
          >
            {tags.map((tag, index) => (
              <Tag key={index} color="success" mr="2" mt="2">
                {tag}
              </Tag>
            ))}
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Justify Content

The `justifyContent` prop controls how flex items are aligned along the main axis. This determines the distribution of space between and around items.

| Property                         | Bulma Class                        | CSS Property                     |
| -------------------------------- | ---------------------------------- | -------------------------------- |
| `justifyContent="flex-start"`    | `is-justify-content-flex-start`    | `justify-content: flex-start`    |
| `justifyContent="flex-end"`      | `is-justify-content-flex-end`      | `justify-content: flex-end`      |
| `justifyContent="center"`        | `is-justify-content-center`        | `justify-content: center`        |
| `justifyContent="space-between"` | `is-justify-content-space-between` | `justify-content: space-between` |
| `justifyContent="space-around"`  | `is-justify-content-space-around`  | `justify-content: space-around`  |
| `justifyContent="space-evenly"`  | `is-justify-content-space-evenly`  | `justify-content: space-evenly`  |
| `justifyContent="start"`         | `is-justify-content-start`         | `justify-content: start`         |
| `justifyContent="end"`           | `is-justify-content-end`           | `justify-content: end`           |
| `justifyContent="left"`          | `is-justify-content-left`          | `justify-content: left`          |
| `justifyContent="right"`         | `is-justify-content-right`         | `justify-content: right`         |

### Justify Content Examples

```tsx live

function JustifyContentExamples() {
  const justifyOptions = [
    { value: 'flex-start', label: 'Flex Start' },
    { value: 'center', label: 'Center' },
    { value: 'flex-end', label: 'Flex End' },
    { value: 'space-between', label: 'Space Between' },
    { value: 'space-around', label: 'Space Around' },
    { value: 'space-evenly', label: 'Space Evenly' },
  ];

  return (
    <Box p="4">
      {justifyOptions.map(({ value, label }) => (
        <Card key={value} mb="4">
          <Card.Header>
            <Card.Header.Title>{label}</Card.Header.Title>
          </Card.Header>
          <Card.Content>
            <Box
              display="flex"
              justifyContent={value as any}
              backgroundColor="light"
              p="3"
            >
              <Button color="primary" size="small">
                A
              </Button>
              <Button color="info" size="small">
                B
              </Button>
              <Button color="success" size="small">
                C
              </Button>
            </Box>
          </Card.Content>
        </Card>
      ))}
    </Box>
  );
}
```

## Align Content

The `alignContent` prop controls how wrapped flex lines are aligned along the cross axis. This only applies when there are multiple lines of flex items.

| Property                       | Bulma Class                      | CSS Property                   |
| ------------------------------ | -------------------------------- | ------------------------------ |
| `alignContent="flex-start"`    | `is-align-content-flex-start`    | `align-content: flex-start`    |
| `alignContent="flex-end"`      | `is-align-content-flex-end`      | `align-content: flex-end`      |
| `alignContent="center"`        | `is-align-content-center`        | `align-content: center`        |
| `alignContent="space-between"` | `is-align-content-space-between` | `align-content: space-between` |
| `alignContent="space-around"`  | `is-align-content-space-around`  | `align-content: space-around`  |
| `alignContent="space-evenly"`  | `is-align-content-space-evenly`  | `align-content: space-evenly`  |
| `alignContent="stretch"`       | `is-align-content-stretch`       | `align-content: stretch`       |

### Align Content Examples

```tsx live

function AlignContentExamples() {
  const items = ['Item 1', 'Item 2', 'Item 3', 'Item 4', 'Item 5', 'Item 6'];

  const alignOptions = [
    { value: 'flex-start', label: 'Flex Start' },
    { value: 'center', label: 'Center' },
    { value: 'flex-end', label: 'Flex End' },
    { value: 'space-between', label: 'Space Between' },
    { value: 'space-around', label: 'Space Around' },
    { value: 'stretch', label: 'Stretch' },
  ];

  return (
    <Box p="4">
      <Content mb="4">
        Note: align-content only affects containers with
        multiple lines of wrapped items.
      </Content>

      {alignOptions.map(({ value, label }) => (
        <Card key={value} mb="4">
          <Card.Header>
            <Card.Header.Title>{label}</Card.Header.Title>
          </Card.Header>
          <Card.Content>
            <Box
              display="flex"
              flexWrap="wrap"
              alignContent={value as any}
              backgroundColor="light"
              p="3"
              style={{ height: '150px' }}
            >
              {items.map((item, index) => (
                <Tag key={index} color="info" mr="1" mb="1" size="small">
                  {item}
                </Tag>
              ))}
            </Box>
          </Card.Content>
        </Card>
      ))}
    </Box>
  );
}
```

## Align Items

The `alignItems` prop controls how flex items are aligned along the cross axis. This affects all items in the flex container.

| Property                  | Bulma Class                 | CSS Property              |
| ------------------------- | --------------------------- | ------------------------- |
| `alignItems="stretch"`    | `is-align-items-stretch`    | `align-items: stretch`    |
| `alignItems="flex-start"` | `is-align-items-flex-start` | `align-items: flex-start` |
| `alignItems="flex-end"`   | `is-align-items-flex-end`   | `align-items: flex-end`   |
| `alignItems="center"`     | `is-align-items-center`     | `align-items: center`     |
| `alignItems="baseline"`   | `is-align-items-baseline`   | `align-items: baseline`   |
| `alignItems="start"`      | `is-align-items-start`      | `align-items: start`      |
| `alignItems="end"`        | `is-align-items-end`        | `align-items: end`        |

### Align Items Examples

```tsx live

function AlignItemsExamples() {
  const alignOptions = [
    { value: 'stretch', label: 'Stretch (Default)' },
    { value: 'flex-start', label: 'Flex Start' },
    { value: 'center', label: 'Center' },
    { value: 'flex-end', label: 'Flex End' },
    { value: 'baseline', label: 'Baseline' },
  ];

  return (
    <Box p="4">
      {alignOptions.map(({ value, label }) => (
        <Card key={value} mb="4">
          <Card.Header>
            <Card.Header.Title>{label}</Card.Header.Title>
          </Card.Header>
          <Card.Content>
            <Box
              display="flex"
              alignItems={value as any}
              backgroundColor="light"
              p="3"
            >
              <Button color="primary" size="small" mr="2">
                Small
              </Button>
              <Button color="info" mr="2">
                Medium
              </Button>
              <Button color="success" size="large">
                Large
              </Button>
            </Box>
          </Card.Content>
        </Card>
      ))}
    </Box>
  );
}
```

## Align Self

The `alignSelf` prop allows individual flex items to override the `alignItems` value set on their container. This provides fine-grained control over individual item alignment.

| Property                 | Bulma Class                | CSS Property             |
| ------------------------ | -------------------------- | ------------------------ |
| `alignSelf="auto"`       | `is-align-self-auto`       | `align-self: auto`       |
| `alignSelf="flex-start"` | `is-align-self-flex-start` | `align-self: flex-start` |
| `alignSelf="flex-end"`   | `is-align-self-flex-end`   | `align-self: flex-end`   |
| `alignSelf="center"`     | `is-align-self-center`     | `align-self: center`     |
| `alignSelf="baseline"`   | `is-align-self-baseline`   | `align-self: baseline`   |
| `alignSelf="stretch"`    | `is-align-self-stretch`    | `align-self: stretch`    |

The `alignSelf` prop allows individual flex items to override the `alignItems` value set on their container. This property applies to elements that are flex items (children of a flex container), not to the flex container itself.

**Important:** The element using `alignSelf` doesn't need `display="flex"` - it just needs to be a child of a flex container.

### Align Self Examples

```tsx live

function AlignSelfExamples() {
  return (
    <Box p="4">
      <Card>
        <Card.Header>
          <Card.Header.Title>Individual Item Alignment</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content mb="3">
            Container has alignItems="flex-start", but individual items override
            with alignSelf:
          </Content>
          <Box
            display="flex"
            alignItems="flex-start"
            bgColor="light"
            p="3"
            style={{ height: '150px' }}
          >
            <Button color="primary" alignSelf="flex-start" mr="2">
              Flex Start
            </Button>
            <Button color="info" alignSelf="center" mr="2">
              Center
            </Button>
            <Button color="success" alignSelf="flex-end" mr="2">
              Flex End
            </Button>
            <Button color="warning" alignSelf="stretch">
              Stretch
            </Button>
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Flex Grow and Shrink

The `flexGrow` and `flexShrink` props control how flex items grow and shrink relative to each other. These properties are essential for creating responsive layouts where items adjust their size based on available space.

### Flex Grow

| Property       | Bulma Class      | CSS Property   |
| -------------- | ---------------- | -------------- |
| `flexGrow="0"` | `is-flex-grow-0` | `flex-grow: 0` |
| `flexGrow="1"` | `is-flex-grow-1` | `flex-grow: 1` |
| `flexGrow="2"` | `is-flex-grow-2` | `flex-grow: 2` |
| `flexGrow="3"` | `is-flex-grow-3` | `flex-grow: 3` |
| `flexGrow="4"` | `is-flex-grow-4` | `flex-grow: 4` |
| `flexGrow="5"` | `is-flex-grow-5` | `flex-grow: 5` |

### Flex Shrink

| Property         | Bulma Class        | CSS Property     |
| ---------------- | ------------------ | ---------------- |
| `flexShrink="0"` | `is-flex-shrink-0` | `flex-shrink: 0` |
| `flexShrink="1"` | `is-flex-shrink-1` | `flex-shrink: 1` |
| `flexShrink="2"` | `is-flex-shrink-2` | `flex-shrink: 2` |
| `flexShrink="3"` | `is-flex-shrink-3` | `flex-shrink: 3` |
| `flexShrink="4"` | `is-flex-shrink-4` | `flex-shrink: 4` |
| `flexShrink="5"` | `is-flex-shrink-5` | `flex-shrink: 5` |

### Flex Grow and Shrink Examples

```tsx live

function FlexGrowShrinkExamples() {
  return (
    <Box p="4">
      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Flex Grow</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content mb="3">
            Items grow to fill available space based on their flex-grow value:
          </Content>
          <Box
            display="flex"
            backgroundColor="light"
            p="3"
            style={{ height: '150px' }}
          >
            <Button color="primary" flexGrow="0" mr="2">
              Grow 0 (Fixed)
            </Button>
            <Button color="info" flexGrow="1" mr="2">
              Grow 1
            </Button>
            <Button color="success" flexGrow="2">
              Grow 2 (2x as much)
            </Button>
          </Box>
        </Card.Content>
      </Card>

      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Flex Shrink</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content mb="3">
            Items shrink when space is limited based on their flex-shrink value:
          </Content>
          <Box
            display="flex"
            backgroundColor="light"
            p="3"
            style={{ height: '150px' }}
          >
            <Button color="primary" flexShrink="0" mr="2">
              No Shrink
            </Button>
            <Button color="info" flexShrink="1" mr="2">
              Shrink 1
            </Button>
            <Button color="success" flexShrink="3">
              Shrink 3
            </Button>
          </Box>
        </Card.Content>
      </Card>

      <Card>
        <Card.Header>
          <Card.Header.Title>Combined Grow and Shrink</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content mb="3">
            Responsive layout that adapts to container size:
          </Content>
          <Box
            display="flex"
            backgroundColor="light"
            p="3"
            style={{ height: '150px' }}
          >
            <Box
              backgroundColor="primary"
              color="white"
              p="2"
              mr="2"
              flexGrow="1"
              flexShrink="1"
              textAlign="centered"
            >
              Sidebar (1:1)
            </Box>
            <Box
              backgroundColor="info"
              color="white"
              p="2"
              mr="2"
              flexGrow="3"
              flexShrink="1"
              textAlign="centered"
            >
              Main Content (3:1)
            </Box>
            <Box
              backgroundColor="success"
              color="white"
              p="2"
              flexGrow="1"
              flexShrink="2"
              textAlign="centered"
            >
              Aside (1:2)
            </Box>
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Complete Layout Example

Here's a comprehensive example showing how to combine multiple flexbox properties to create a complex, responsive layout:

```tsx live
// import {
//   Box,
//   Card,
//   Title,
//   Content,
//   Button,
//   Tag,
// } from '@allxsmith/bestax-bulma';

function ComplexFlexboxLayout() {
  return (
    <Box p="4">
      <Card>
        <Card.Header>
          <Card.Header.Title>Complex Flexbox Layout</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          {/* Main container */}
          <Box display="flex" flexDirection="column">
            {/* Header */}
            <Box
              display="flex"
              justifyContent="space-between"
              alignItems="center"
              backgroundColor="primary"
              color="white"
              p="3"
              flexShrink="0"
            >
              <Title size="5" color="white" mb="0">
                Dashboard
              </Title>
              <Box display="flex" alignItems="center">
                <Tag color="light" mr="2">
                  Status: Online
                </Tag>
                <Button color="light" size="small">
                  Settings
                </Button>
              </Box>
            </Box>

            {/* Content area */}
            <Box display="flex" flexGrow="1">
              {/* Sidebar */}
              <Box flexShrink="0" mb="0">
                Navigation
                
                  Dashboard
                  Analytics
                  Reports
                  Settings
                
              </Box>

              {/* Main content */}
              <Box flexGrow="1" p="4" display="flex" flexDirection="column">
                <Title size="4" mb="3">
                  Welcome to the Dashboard
                </Title>

                {/* Cards grid */}
                <Box
                  display="flex"
                  flexWrap="wrap"
                  justifyContent="space-between"
                  flexGrow="1"
                >
                  <Box
                    backgroundColor="info"
                    color="white"
                    p="3"
                    mb="3"
                    display="flex"
                    alignItems="center"
                    justifyContent="center"
                  >
                    Card 1
                  </Box>
                  <Box
                    backgroundColor="success"
                    color="white"
                    p="3"
                    mb="3"
                    display="flex"
                    alignItems="center"
                    justifyContent="center"
                  >
                    Card 2
                  </Box>
                  <Box
                    backgroundColor="warning"
                    color="white"
                    p="3"
                    display="flex"
                    alignItems="center"
                    justifyContent="center"
                  >
                    Card 3
                  </Box>
                  <Box
                    backgroundColor="danger"
                    color="white"
                    p="3"
                    display="flex"
                    alignItems="center"
                    justifyContent="center"
                  >
                    Card 4
                  </Box>
                </Box>
              </Box>
            </Box>

            {/* Footer */}
            <Box
              display="flex"
              justifyContent="center"
              alignItems="center"
              backgroundColor="dark"
              color="white"
              p="2"
              flexShrink="0"
            >
              <Content color="white" mb="0" textAlign="centered">
                © 2025 Your Company. All rights reserved.
              </Content>
            </Box>
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Best Practices

:::tip Flexbox Guidelines

1. **Start with display="flex"**: Always set `display="flex"` on the container before using flexbox properties
2. **Understand the axes**: Remember that flexbox has a main axis (flex-direction) and a cross axis (perpendicular)
3. **Use semantic properties**: Choose properties that clearly express your layout intent
4. **Combine with responsive props**: Use viewport props for responsive flexbox layouts
5. **Test with different content**: Ensure your layout works with varying content sizes

:::

### Common Flexbox Patterns

```tsx live

function CommonFlexboxPatterns() {
  return (
    <Box p="4">
      {/* Centered content */}
      <Box mb="6">
        <Title size="5" mb="3">
          Centered Content
        </Title>
        <Box display="flex" justifyContent="center" alignItems="center">
          <Content mb="0" textAlign="centered">
            Perfectly centered
          </Content>
        </Box>
      </Box>

      {/* Navigation bar */}
      <Box mb="6">
        <Title size="5" mb="3">
          Navigation Bar Layout
        </Title>
        <Box
          display="flex"
          justifyContent="space-between"
          alignItems="center"
          backgroundColor="primary"
          textColor="white"
          p="3"
        >
          <Title textColor="white" mb="0">
            Logo
          </Title>
          <Box display="flex">
            <Button color="light" mr="2">
              Home
            </Button>
            <Button color="light" mr="2">
              About
            </Button>
            <Button color="light">Contact</Button>
          </Box>
        </Box>
      </Box>

      {/* Responsive grid alternative */}
      <Box mb="6">
        <Title size="5" mb="3">
          Responsive Grid Alternative
        </Title>
        <Box
          display="flex"
          flexWrap="wrap"
          justifyContent="space-between"
          p="3"
        >
          <Box
            mb="3"
            backgroundColor="info"
            textColor="white"
            p="3"
            textAlign="centered"
          >
            Card 1
          </Box>
          <Box
            mb="3"
            backgroundColor="success"
            textColor="white"
            p="3"
            textAlign="centered"
          >
            Card 2
          </Box>
          <Box
            mb="3"
            backgroundColor="warning"
            textColor="white"
            p="3"
            textAlign="centered"
          >
            Card 3
          </Box>
          <Box
            mb="3"
            backgroundColor="danger"
            textColor="white"
            p="3"
            textAlign="centered"
          >
            Card 4
          </Box>
        </Box>
      </Box>

      {/* Sticky footer layout */}
      <Box>
        <Title size="5" mb="3">
          Sticky Footer Layout
        </Title>
        <Box display="flex" flexDirection="column" backgroundColor="light">
          <Box
            backgroundColor="primary"
            textColor="white"
            p="3"
            textAlign="centered"
          >
            Header
          </Box>
          <Box flexGrow="1" p="4" textAlign="centered">
            Main content area that grows to fill available space
          </Box>
          <Box
            backgroundColor="dark"
            textColor="white"
            p="3"
            textAlign="centered"
          >
            Footer
          </Box>
        </Box>
      </Box>
    </Box>
  );
}
```

:::tip Learn More

For detailed API information about flexbox properties, see the [useBulmaClasses API documentation](/docs/api/helpers/usebulmaclasses).

:::

## See Also

- [useBulmaClasses](/docs/api/helpers/usebulmaclasses) - Complete flexbox property reference
- [Visibility Helpers](/docs/guides/helpers/visibility) - Display and visibility utilities
- [Responsive Design](/docs/guides/features/responsiveness) - Responsive flexbox techniques
- [Layout Components](/docs/guides/library/layout) - Layout components that use flexbox
- [Bulma Flexbox Documentation](https://bulma.io/documentation/helpers/flexbox-helpers/) - Official Bulma flexbox helpers

---

## Margin & Padding


Bulma provides a comprehensive spacing system using margin and padding helpers. These utilities allow you to add consistent spacing throughout your application without writing custom CSS.

:::tip Composable hook

These props are also available standalone via the `useSpacingClasses` hook — see [Composable Mini-Hooks](/docs/api/helpers/usebulmaclasses#composable-mini-hooks).

:::

:::info Reference

This page documents the bestax-bulma prop API for Bulma's spacing helpers. For the underlying CSS utilities, see the [official Bulma spacing helpers](https://bulma.io/documentation/helpers/spacing-helpers/).

:::

:::tip

All components in bestax-bulma have access to these spacing properties through the `useBulmaClasses` hook. You can apply margin and padding to any component in the library for consistent spacing.

:::

## Margin

Use margin props to add external spacing around elements. Margin creates space outside the element's border.

### All Sides Margin

| Property   | Bulma Class | Value   |
| ---------- | ----------- | ------- |
| `m="0"`    | `m-0`       | 0       |
| `m="1"`    | `m-1`       | 0.25rem |
| `m="2"`    | `m-2`       | 0.5rem  |
| `m="3"`    | `m-3`       | 0.75rem |
| `m="4"`    | `m-4`       | 1rem    |
| `m="5"`    | `m-5`       | 1.5rem  |
| `m="6"`    | `m-6`       | 3rem    |
| `m="auto"` | `m-auto`    | auto    |

### Top Margin

| Property    | Bulma Class | Value   |
| ----------- | ----------- | ------- |
| `mt="0"`    | `mt-0`      | 0       |
| `mt="1"`    | `mt-1`      | 0.25rem |
| `mt="2"`    | `mt-2`      | 0.5rem  |
| `mt="3"`    | `mt-3`      | 0.75rem |
| `mt="4"`    | `mt-4`      | 1rem    |
| `mt="5"`    | `mt-5`      | 1.5rem  |
| `mt="6"`    | `mt-6`      | 3rem    |
| `mt="auto"` | `mt-auto`   | auto    |

### Right Margin

| Property    | Bulma Class | Value   |
| ----------- | ----------- | ------- |
| `mr="0"`    | `mr-0`      | 0       |
| `mr="1"`    | `mr-1`      | 0.25rem |
| `mr="2"`    | `mr-2`      | 0.5rem  |
| `mr="3"`    | `mr-3`      | 0.75rem |
| `mr="4"`    | `mr-4`      | 1rem    |
| `mr="5"`    | `mr-5`      | 1.5rem  |
| `mr="6"`    | `mr-6`      | 3rem    |
| `mr="auto"` | `mr-auto`   | auto    |

### Bottom Margin

| Property    | Bulma Class | Value   |
| ----------- | ----------- | ------- |
| `mb="0"`    | `mb-0`      | 0       |
| `mb="1"`    | `mb-1`      | 0.25rem |
| `mb="2"`    | `mb-2`      | 0.5rem  |
| `mb="3"`    | `mb-3`      | 0.75rem |
| `mb="4"`    | `mb-4`      | 1rem    |
| `mb="5"`    | `mb-5`      | 1.5rem  |
| `mb="6"`    | `mb-6`      | 3rem    |
| `mb="auto"` | `mb-auto`   | auto    |

### Left Margin

| Property    | Bulma Class | Value   |
| ----------- | ----------- | ------- |
| `ml="0"`    | `ml-0`      | 0       |
| `ml="1"`    | `ml-1`      | 0.25rem |
| `ml="2"`    | `ml-2`      | 0.5rem  |
| `ml="3"`    | `ml-3`      | 0.75rem |
| `ml="4"`    | `ml-4`      | 1rem    |
| `ml="5"`    | `ml-5`      | 1.5rem  |
| `ml="6"`    | `ml-6`      | 3rem    |
| `ml="auto"` | `ml-auto`   | auto    |

### Horizontal Margin (Left + Right)

| Property    | Bulma Class | Value   |
| ----------- | ----------- | ------- |
| `mx="0"`    | `mx-0`      | 0       |
| `mx="1"`    | `mx-1`      | 0.25rem |
| `mx="2"`    | `mx-2`      | 0.5rem  |
| `mx="3"`    | `mx-3`      | 0.75rem |
| `mx="4"`    | `mx-4`      | 1rem    |
| `mx="5"`    | `mx-5`      | 1.5rem  |
| `mx="6"`    | `mx-6`      | 3rem    |
| `mx="auto"` | `mx-auto`   | auto    |

### Vertical Margin (Top + Bottom)

| Property    | Bulma Class | Value   |
| ----------- | ----------- | ------- |
| `my="0"`    | `my-0`      | 0       |
| `my="1"`    | `my-1`      | 0.25rem |
| `my="2"`    | `my-2`      | 0.5rem  |
| `my="3"`    | `my-3`      | 0.75rem |
| `my="4"`    | `my-4`      | 1rem    |
| `my="5"`    | `my-5`      | 1.5rem  |
| `my="6"`    | `my-6`      | 3rem    |
| `my="auto"` | `my-auto`   | auto    |

### Margin Examples

```tsx live

function MarginExamples() {
  return (
    <Box p="4">
      <Title mb="4">Margin Examples</Title>

      {/* All sides margin */}
      <Box backgroundColor="light" color="dark" p="2" m="4" mb="4">
        Box with margin on all sides (m="4")
      </Box>

      {/* Specific side margins */}
      <Box
        backgroundColor="info"
        color="dark"
        p="2"
        mt="3"
        mr="6"
        mb="2"
        ml="1"
      >
        Box with different margins on each side
      </Box>

      {/* Horizontal and vertical margins */}
      <Box
        backgroundColor="success"
        color="white"
        p="2"
        mx="auto"
        my="3"
        style={{ width: '200px' }}
      >
        Centered box with vertical margin
      </Box>

      {/* Button spacing */}
      
        <Button mr="2">First Button</Button>
        <Button mr="2">Second Button</Button>
        <Button>Third Button</Button>
      

      {/* Card spacing */}
      <Card mt="5" mb="3">
        <Card.Content>Card with top and bottom margins</Card.Content>
      </Card>
    </Box>
  );
}
```

## Padding

Use padding props to add internal spacing within elements. Padding creates space inside the element's border.

### All Sides Padding

| Property | Bulma Class | Value   |
| -------- | ----------- | ------- |
| `p="0"`  | `p-0`       | 0       |
| `p="1"`  | `p-1`       | 0.25rem |
| `p="2"`  | `p-2`       | 0.5rem  |
| `p="3"`  | `p-3`       | 0.75rem |
| `p="4"`  | `p-4`       | 1rem    |
| `p="5"`  | `p-5`       | 1.5rem  |
| `p="6"`  | `p-6`       | 3rem    |

### Top Padding

| Property | Bulma Class | Value   |
| -------- | ----------- | ------- |
| `pt="0"` | `pt-0`      | 0       |
| `pt="1"` | `pt-1`      | 0.25rem |
| `pt="2"` | `pt-2`      | 0.5rem  |
| `pt="3"` | `pt-3`      | 0.75rem |
| `pt="4"` | `pt-4`      | 1rem    |
| `pt="5"` | `pt-5`      | 1.5rem  |
| `pt="6"` | `pt-6`      | 3rem    |

### Right Padding

| Property | Bulma Class | Value   |
| -------- | ----------- | ------- |
| `pr="0"` | `pr-0`      | 0       |
| `pr="1"` | `pr-1`      | 0.25rem |
| `pr="2"` | `pr-2`      | 0.5rem  |
| `pr="3"` | `pr-3`      | 0.75rem |
| `pr="4"` | `pr-4`      | 1rem    |
| `pr="5"` | `pr-5`      | 1.5rem  |
| `pr="6"` | `pr-6`      | 3rem    |

### Bottom Padding

| Property | Bulma Class | Value   |
| -------- | ----------- | ------- |
| `pb="0"` | `pb-0`      | 0       |
| `pb="1"` | `pb-1`      | 0.25rem |
| `pb="2"` | `pb-2`      | 0.5rem  |
| `pb="3"` | `pb-3`      | 0.75rem |
| `pb="4"` | `pb-4`      | 1rem    |
| `pb="5"` | `pb-5`      | 1.5rem  |
| `pb="6"` | `pb-6`      | 3rem    |

### Left Padding

| Property | Bulma Class | Value   |
| -------- | ----------- | ------- |
| `pl="0"` | `pl-0`      | 0       |
| `pl="1"` | `pl-1`      | 0.25rem |
| `pl="2"` | `pl-2`      | 0.5rem  |
| `pl="3"` | `pl-3`      | 0.75rem |
| `pl="4"` | `pl-4`      | 1rem    |
| `pl="5"` | `pl-5`      | 1.5rem  |
| `pl="6"` | `pl-6`      | 3rem    |

### Horizontal Padding (Left + Right)

| Property | Bulma Class | Value   |
| -------- | ----------- | ------- |
| `px="0"` | `px-0`      | 0       |
| `px="1"` | `px-1`      | 0.25rem |
| `px="2"` | `px-2`      | 0.5rem  |
| `px="3"` | `px-3`      | 0.75rem |
| `px="4"` | `px-4`      | 1rem    |
| `px="5"` | `px-5`      | 1.5rem  |
| `px="6"` | `px-6`      | 3rem    |

### Vertical Padding (Top + Bottom)

| Property | Bulma Class | Value   |
| -------- | ----------- | ------- |
| `py="0"` | `py-0`      | 0       |
| `py="1"` | `py-1`      | 0.25rem |
| `py="2"` | `py-2`      | 0.5rem  |
| `py="3"` | `py-3`      | 0.75rem |
| `py="4"` | `py-4`      | 1rem    |
| `py="5"` | `py-5`      | 1.5rem  |
| `py="6"` | `py-6`      | 3rem    |

### Padding Examples

```tsx live
// import {
//   Box,
//   Card,
//   Notification,
//   Button,
//   Title,
// } from '@allxsmith/bestax-bulma';

function PaddingExamples() {
  return (
    <Box p="4">
      <Title mb="4">Padding Examples</Title>

      {/* All sides padding */}
      <Box backgroundColor="primary" color="white" p="6" mb="4">
        Box with large padding on all sides (p="6")
      </Box>

      {/* Specific side padding */}
      <Box
        backgroundColor="info"
        color="dark"
        pt="1"
        pr="4"
        pb="2"
        pl="6"
        mb="4"
      >
        Box with different padding on each side
      </Box>

      {/* Horizontal and vertical padding */}
      <Box backgroundColor="success" color="white" px="5" py="2" mb="4">
        Box with horizontal and vertical padding
      </Box>

      {/* Card with custom padding */}
      <Card mb="4">
        <Card.Content p="6">
          <Title size="5" mb="3">
            Card with Custom Padding
          </Title>
          
            This card content has extra padding (p="6") for a more spacious
            feel.
          
        </Card.Content>
      </Card>

      {/* Notification with minimal padding */}
      <Notification color="warning" p="2" mb="4">
        Compact notification with minimal padding
      </Notification>

      {/* Button with custom padding */}
      <Button px="6" py="3" backgroundColor="danger" color="white">
        Button with Custom Padding
      </Button>
    </Box>
  );
}
```

## Combining Margin and Padding

You can combine margin and padding properties to create sophisticated spacing layouts:

```tsx live

function CombinedSpacingExample() {
  return (
    <Box p="4">
      <Title mb="5">Combined Spacing Example</Title>

      {/* Article-style layout */}
      <Card mx="auto" my="4" p="0" style={{ maxWidth: '600px' }}>
        <Card.Content pt="6" px="6" pb="4">
          <Title size="3" mb="3">
            Article Title
          </Title>
          <Content mb="4">
            
              This is an example of combining margin and padding for a clean
              article layout with proper spacing.
            
          </Content>
        </Card.Content>

        <Card.Content pt="0" px="6" pb="6">
          <Box backgroundColor="light" color="dark" p="4" mb="4">
            <Content>
              
                This is a highlighted section with its own padding and margin
                within the card.
              
            </Content>
          </Box>

          <Button mr="3" px="4" py="2">
            Read More
          </Button>
          <Button variant="outlined" px="4" py="2" color="dark">
            Share
          </Button>
        </Card.Content>
      </Card>

      {/* Grid-like layout with spacing */}
      <Box mt="6">
        <Title size="4" mb="4">
          Grid Layout with Spacing
        </Title>
        <Box display="flex" flexWrap="wrap" mx="-2">
          {[1, 2, 3, 4, 5, 6].map(num => (
            <Box key={num} style={{ width: '33.333%' }} px="2" mb="4">
              <Card p="4" backgroundColor="light" color="dark">
                <Title size="6" mb="2" color="dark">
                  Item {num}
                </Title>
                <Content>
                  Content with consistent spacing using margin and padding.
                </Content>
              </Card>
            </Box>
          ))}
        </Box>
      </Box>
    </Box>
  );
}
```

## Best Practices

:::tip Spacing Guidelines

1. **Default First**: Prefer using component default spacing before customizing
2. **Consistency**: Use the spacing scale consistently throughout your application
3. **Hierarchy**: Use larger spacing values to create visual hierarchy
4. **Rhythm**: Establish vertical rhythm with consistent margin values
5. **Semantic spacing**: Use spacing to group related content together

:::

### Recommended Spacing Patterns

:::tip Best Practice

The recommended approach is to use the default padding and spacing that comes built into Bulma components. Components are designed with appropriate spacing out of the box. Only override spacing when absolutely necessary for your specific design requirements.

:::

```tsx
// PREFERRED: Use default component spacing
<Card>                    // Uses default Card spacing
  <Card.Content>          // Uses default Content spacing
    <Title>               // Uses default Title spacing
    <Content>             // Uses default Content spacing
    <Button>              // Uses default Button spacing
</Card>

// ACCEPTABLE: Override only when needed
// (In an imperfect world, sometimes customization is necessary)
<Card m="3">              // Override only when layout requires it
  <Card.Content p="5">    // Override only for specific design needs
    <Title mb="3">        // Override only when default doesn't work
    <Content mb="4">      // Override sparingly
    <Button mt="3">       // Override as last resort
</Card>

// AVOID: Excessive spacing overrides
<Card m="3" p="0" mx="auto" my="5">     // Too many overrides
  <Card.Content p="5" pt="6" pb="4">    // Overly complex spacing
    <Title mb="3" mt="2" mx="1">        // Unnecessary customization
```

:::warning Override with Caution

While spacing overrides are available and sometimes necessary, they should be used sparingly. Excessive customization can lead to inconsistent designs and maintenance challenges. When you do override default spacing, document your reasoning and ensure it aligns with your design system.

:::

:::tip Learn More

For detailed API information about spacing properties, see the [useBulmaClasses API documentation](/docs/api/helpers/usebulmaclasses).

:::

## See Also

- [useBulmaClasses](/docs/api/helpers/usebulmaclasses) - Complete spacing property reference
- [Responsive Design](/docs/guides/features/responsiveness) - Responsive spacing techniques
- [Layout Components](/docs/guides/library/layout) - Layout components with built-in spacing
- [Bulma Spacing Documentation](https://bulma.io/documentation/helpers/spacing-helpers/) - Official Bulma spacing helpers

---

## Other Helpers


Bulma provides a collection of additional utility helpers that solve common CSS challenges and provide convenient styling shortcuts. These miscellaneous helpers are essential for fine-tuning layouts and addressing specific design requirements.

:::tip Composable hook

These props are also available standalone via the `useOtherClasses` hook — see [Composable Mini-Hooks](/docs/api/helpers/usebulmaclasses#composable-mini-hooks).

:::

:::info Reference

This page documents the bestax-bulma prop API for Bulma's other helpers. For the underlying CSS utilities, see the [official Bulma other helpers](https://bulma.io/documentation/helpers/other-helpers/).

:::

:::tip

Many of these helpers are available as direct props through the `useBulmaClasses` hook in bestax-bulma, providing a clean and type-safe way to apply these utility styles to any component in the library.

:::

## Float

The float helpers allow you to move elements to the left or right of their container. These are useful for creating simple layouts and aligning content within containers.

| Property        | Bulma Class       | CSS Property   |
| --------------- | ----------------- | -------------- |
| `float="left"`  | `is-pulled-left`  | `float: left`  |
| `float="right"` | `is-pulled-right` | `float: right` |

Float helpers are particularly useful for aligning elements within text content or creating simple two-column layouts.

### Float Examples

```tsx

function FloatExamples() {
  return (
    <Box p="4">
      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Float Left</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content>
            <Box
              float="left"
              backgroundColor="primary"
              color="white"
              p="3"
              mr="3"
              mb="2"
              style={{ width: '150px' }}
            >
              Floated Left
            </Box>
            This text flows around the floated element on the left. Lorem ipsum
            dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
            incididunt ut labore et dolore magna aliqua. Ut enim ad minim
            veniam, quis nostrud exercitation ullamco laboris.
          </Content>
        </Card.Content>
      </Card>

      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Float Right</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content>
            <Box
              float="right"
              backgroundColor="info"
              color="white"
              p="3"
              ml="3"
              mb="2"
              style={{ width: '150px' }}
            >
              Floated Right
            </Box>
            This text flows around the floated element on the right. Lorem ipsum
            dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor
            incididunt ut labore et dolore magna aliqua. Ut enim ad minim
            veniam, quis nostrud exercitation ullamco laboris.
          </Content>
        </Card.Content>
      </Card>

      <Card>
        <Card.Header>
          <Card.Header.Title>
            Practical Example: Article with Image
          </Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content>
            <Image
              src="https://bulma.io/assets/images/placeholders/256x256.png"
              alt="Article image"
              float="left"
              mr="3"
              mb="3"
              style={{ width: '128px', height: '128px' }}
            />
            Article Title: This is how you can create an
            article layout with a floating image. The image floats to the left
            while the text content flows around it naturally. This is a common
            pattern in blog posts, news articles, and content-heavy websites.
            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
            eiusmod tempor incididunt ut labore et dolore magna aliqua.
          </Content>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Clearfix

The clearfix helper fixes an element's floating children by clearing floats. This is essential when you have floating elements inside a container and need the container to properly wrap around them.

| Property          | Bulma Class   | CSS Property             |
| ----------------- | ------------- | ------------------------ |
| `clearfix={true}` | `is-clearfix` | Clears floating children |

The clearfix helper fixes an element's floating children by clearing floats. This is essential when you have floating elements inside a container and need the container to properly wrap around them.

### Clearfix Examples

```tsx

function ClearfixExamples() {
  return (
    <Box p="4">
      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Without Clearfix</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content mb="3">
            This container doesn't clear its floating children, so it collapses:
          </Content>
          <Box backgroundColor="danger" p="3" color="white">
            <Box float="left" backgroundColor="white" color="dark" p="2" mr="2">
              Float Left
            </Box>
            <Box float="right" backgroundColor="white" color="dark" p="2">
              Float Right
            </Box>
            {/* Container collapses because it doesn't clear floats */}
          </Box>
        </Card.Content>
      </Card>

      <Card>
        <Card.Header>
          <Card.Header.Title>With Clearfix</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content mb="3">
            This container properly contains its floating children:
          </Content>
          <Box backgroundColor="success" p="3" color="white" clearfix>
            <Box float="left" backgroundColor="white" color="dark" p="2" mr="2">
              Float Left
            </Box>
            <Box float="right" backgroundColor="white" color="dark" p="2">
              Float Right
            </Box>
            {/* Container properly wraps around floating children */}
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Overlay

The overlay helper completely covers the first positioned parent element. This is useful for creating modal backdrops, loading overlays, or image overlays.

| Property         | Bulma Class  | CSS Property                        |
| ---------------- | ------------ | ----------------------------------- |
| `overlay={true}` | `is-overlay` | Absolutely positioned full coverage |

:::warning Positioning Requirement

The overlay helper requires the parent element to have `position: relative`, `position: absolute`, or `position: fixed` to work correctly.

:::

### Overlay Examples

```tsx

function OverlayExamples() {
  return (
    <Box p="4">
      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Image Overlay</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Box position="relative" style={{ height: '200px' }}>
            <Box
              style={{
                backgroundImage:
                  'url(https://bulma.io/assets/images/placeholders/640x480.png)',
                backgroundSize: 'cover',
                backgroundPosition: 'center',
                height: '100%',
              }}
            />
            <Box
              overlay={true}
              backgroundColor="dark"
              style={{ opacity: 0.7 }}
              display="flex"
              alignItems="center"
              justifyContent="center"
            >
              <Title color="white" size="4" textAlign="centered">
                Overlay Content
              </Title>
            </Box>
          </Box>
        </Card.Content>
      </Card>

      <Card>
        <Card.Header>
          <Card.Header.Title>Loading Overlay</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Box
            position="relative"
            backgroundColor="light"
            p="4"
            style={{ height: '150px' }}
          >
            <Content>
              
                This is the main content that gets covered by the loading
                overlay.
              
              <Button color="primary">Action Button</Button>
            </Content>

            <Box
              overlay={true}
              backgroundColor="white"
              style={{ opacity: 0.9 }}
              display="flex"
              alignItems="center"
              justifyContent="center"
            >
              <Content textAlign="centered">
                <Title size="5" mb="2">
                  Loading...
                </Title>
                <Content>Please wait while we process your request.</Content>
              </Content>
            </Box>
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Overflow

The overflow helper adds `overflow: hidden` to an element, which clips any content that extends beyond the element's boundaries.

| Property             | Bulma Class  | CSS Property       |
| -------------------- | ------------ | ------------------ |
| `overflow="clipped"` | `is-clipped` | `overflow: hidden` |

This is useful for preventing content from overflowing its container and creating clean, contained layouts.

### Overflow Examples

```tsx

function OverflowExamples() {
  return (
    <Box p="4">
      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Without Overflow Control</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Box
            backgroundColor="danger"
            color="white"
            p="3"
            style={{ height: '100px', width: '200px' }}
          >
            This content is much longer than the container and will overflow
            beyond the boundaries, creating a messy layout that extends outside
            the defined area.
          </Box>
        </Card.Content>
      </Card>

      <Card>
        <Card.Header>
          <Card.Header.Title>With Overflow Clipped</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Box
            backgroundColor="success"
            color="white"
            p="3"
            overflow="clipped"
            style={{ height: '100px', width: '200px' }}
          >
            This content is much longer than the container but gets clipped
            cleanly at the boundaries, creating a neat and contained layout that
            doesn't extend outside the defined area.
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Border Radius

The radius helper removes any border radius from an element, making it completely square regardless of default styling.

| Property              | Bulma Class     | CSS Property       |
| --------------------- | --------------- | ------------------ |
| `radius="radiusless"` | `is-radiusless` | `border-radius: 0` |

This is particularly useful when you want to override default rounded corners on components like buttons, cards, or images.

### Border Radius Examples

```tsx

function BorderRadiusExamples() {
  return (
    <Box p="4">
      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Default Rounded Elements</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Box display="flex" alignItems="center" flexWrap="wrap">
            <Button color="primary" mr="2" mb="2">
              Rounded Button
            </Button>
            <Box
              backgroundColor="info"
              color="white"
              p="3"
              mr="2"
              mb="2"
              style={{ borderRadius: '6px' }}
            >
              Rounded Box
            </Box>
            <Image
              src="https://bulma.io/assets/images/placeholders/128x128.png"
              alt="Rounded image"
              style={{ width: '64px', height: '64px', borderRadius: '8px' }}
            />
          </Box>
        </Card.Content>
      </Card>

      <Card>
        <Card.Header>
          <Card.Header.Title>Radiusless Elements</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Box display="flex" alignItems="center" flexWrap="wrap">
            <Button color="primary" radius="radiusless" mr="2" mb="2">
              Square Button
            </Button>
            <Box
              backgroundColor="info"
              color="white"
              p="3"
              mr="2"
              mb="2"
              radius="radiusless"
            >
              Square Box
            </Box>
            <Image
              src="https://bulma.io/assets/images/placeholders/128x128.png"
              alt="Square image"
              radius="radiusless"
              style={{ width: '64px', height: '64px' }}
            />
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Shadow

The shadow helper removes any box shadow from an element, creating a flat appearance.

| Property              | Bulma Class     | CSS Property       |
| --------------------- | --------------- | ------------------ |
| `shadow="shadowless"` | `is-shadowless` | `box-shadow: none` |

This is useful when you want to remove default shadows from components like cards, buttons, or other elevated elements.

### Shadow Examples

```tsx

function ShadowExamples() {
  return (
    <Box p="4">
      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Default Shadow Elements</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Box display="flex" alignItems="center" flexWrap="wrap">
            <Card mr="3" mb="3" style={{ width: '200px' }}>
              <Card.Content>
                <Content>Card with shadow</Content>
              </Card.Content>
            </Card>

            <Box
              backgroundColor="white"
              p="3"
              style={{
                boxShadow: '0 2px 8px rgba(0,0,0,0.1)',
                border: '1px solid #e8e8e8',
              }}
            >
              Box with shadow
            </Box>
          </Box>
        </Card.Content>
      </Card>

      <Card>
        <Card.Header>
          <Card.Header.Title>Shadowless Elements</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Box display="flex" alignItems="center" flexWrap="wrap">
            <Card
              shadow="shadowless"
              mr="3"
              mb="3"
              style={{
                width: '200px',
                border: '1px solid #e8e8e8',
              }}
            >
              <Card.Content>
                <Content>Card without shadow</Content>
              </Card.Content>
            </Card>

            <Box
              backgroundColor="white"
              p="3"
              shadow="shadowless"
              style={{ border: '1px solid #e8e8e8' }}
            >
              Box without shadow
            </Box>
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Interaction

The interaction helpers control user interaction behavior with elements, particularly text selection and cursor appearance.

| Property                     | Bulma Class       | CSS Property                 |
| ---------------------------- | ----------------- | ---------------------------- |
| `interaction="unselectable"` | `is-unselectable` | `user-select: none`          |
| `interaction="clickable"`    | `is-clickable`    | `cursor: pointer !important` |

These helpers are useful for improving user experience by preventing unwanted text selection or indicating clickable elements.

### Interaction Examples

```tsx

function InteractionExamples() {
  return (
    <Box p="4">
      <Card mb="4">
        <Card.Header>
          <Card.Header.Title>Unselectable Text</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content mb="3">
            Try to select the text below - the first paragraph is unselectable:
          </Content>

          <Box
            backgroundColor="info"
            color="white"
            p="3"
            mb="3"
            interaction="unselectable"
          >
            This text cannot be selected by the user. This is useful for UI
            elements, labels, or decorative text that shouldn't be copyable.
          </Box>

          <Box backgroundColor="light" p="3">
            This text can be selected normally. Users can highlight and copy
            this content as they would expect with regular text.
          </Box>
        </Card.Content>
      </Card>

      <Card>
        <Card.Header>
          <Card.Header.Title>Clickable Elements</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content mb="3">
            Hover over the elements below to see cursor changes:
          </Content>

          <Box display="flex" flexDirection="column" style={{ gap: '1rem' }}>
            <Box
              backgroundColor="primary"
              color="white"
              p="3"
              interaction="clickable"
              onClick={() => alert('Clicked!')}
            >
              This box shows a pointer cursor and is clickable
            </Box>

            <Box
              backgroundColor="success"
              color="white"
              p="3"
              interaction="clickable"
              textTransform="uppercase"
              onClick={() => alert('Also clicked!')}
            >
              This box is clickable with uppercase text
            </Box>

            <Box backgroundColor="light" p="3">
              This box shows the default cursor (not clickable)
            </Box>
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Cursor

The `cursor` prop sets the mouse cursor style. `cursor="pointer"` reuses Bulma's built-in `is-clickable` class; `cursor="help"` uses bestax's project-level `is-cursor-help` class to indicate a help/tooltip affordance.

| Property           | Bulma Class      | CSS Property      |
| ------------------ | ---------------- | ----------------- |
| `cursor="pointer"` | `is-clickable`   | `cursor: pointer` |
| `cursor="help"`    | `is-cursor-help` | `cursor: help`    |

### Cursor Examples

```tsx live

function CursorExamples() {
  return (
    <Box p="4">
      <Box
        cursor="pointer"
        backgroundColor="primary"
        color="white"
        p="3"
        mb="3"
      >
        Cursor: pointer (is-clickable)
      </Box>
      <Box cursor="help" backgroundColor="info" color="white" p="3">
        Cursor: help (is-cursor-help)
      </Box>
    </Box>
  );
}
```

## Responsive

The `responsive` prop applies Bulma's always-on responsive modifiers. These are primarily useful on layout components like `Navbar` and `Columns` that have viewport-dependent default behavior.

| Property              | Bulma Class | Typical Use                                              |
| --------------------- | ----------- | -------------------------------------------------------- |
| `responsive="mobile"` | `is-mobile` | Force mobile layout at all viewports (e.g. on `Columns`) |
| `responsive="narrow"` | `is-narrow` | Shrink a column to fit its content                       |

## Full Height

The `fullHeight` prop applies `height: 100%`, useful for making a child fill its positioned parent.

| Property            | Bulma Class      | CSS Property   |
| ------------------- | ---------------- | -------------- |
| `fullHeight={true}` | `is-full-height` | `height: 100%` |

## Skeleton

The `skeleton` prop toggles Bulma's skeleton loading state on a component. See the [skeleton examples in the useBulmaClasses API reference](/docs/api/helpers/usebulmaclasses#skeleton-examples) for per-component usage.

| Property          | Bulma Class   | Effect                  |
| ----------------- | ------------- | ----------------------- |
| `skeleton={true}` | `is-skeleton` | Skeleton loading effect |

## Position Relative

The position relative helper applies `position: relative` to an element, which is essential for creating positioning contexts for absolutely positioned children.

| Property          | Bulma Class   | CSS Property         |
| ----------------- | ------------- | -------------------- |
| `relative={true}` | `is-relative` | `position: relative` |

The position relative helper applies `position: relative` to an element, which is essential for creating positioning contexts for absolutely positioned children.

### Position Relative Examples

```tsx

function PositionRelativeExamples() {
  return (
    <Box p="4">
      <Card>
        <Card.Header>
          <Card.Header.Title>Relative Positioning Context</Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Content mb="3">
            The relative positioned container provides a context for absolutely
            positioned children:
          </Content>

          <Box
            relative
            backgroundColor="light"
            p="4"
            style={{ height: '200px', border: '2px dashed #ccc' }}
          >
            <Content>This container has position: relative</Content>
            <Box
              style={{
                position: 'absolute',
                top: '10px',
                right: '10px',
                background: '#ff5722',
                color: 'white',
                padding: '0.5rem',
                borderRadius: '4px',
              }}
            >
              Absolutely positioned
            </Box>
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Combined Usage Example

Here's a practical example showing how multiple other helpers can work together to create a sophisticated component:

```tsx

  Box,
  Card,
  Title,
  Content,
  Button,
  Image,
} from '@allxsmith/bestax-bulma';

function CombinedHelpersExample() {
  return (
    <Box p="4">
      <Card>
        <Card.Header>
          <Card.Header.Title>
            Product Card with Multiple Helpers
          </Card.Header.Title>
        </Card.Header>
        <Card.Content>
          <Box relative style={{ height: '300px' }}>
            {/* Product image */}
            <Image
              src="https://bulma.io/assets/images/placeholders/400x300.png"
              alt="Product"
              style={{
                width: '100%',
                height: '200px',
                objectFit: 'cover',
              }}
              radius="radiusless"
            />

            {/* Sale badge overlay */}
            <Box
              backgroundColor="danger"
              color="white"
              p="2"
              interaction="unselectable"
              style={{
                position: 'absolute',
                top: '10px',
                right: '10px',
                borderRadius: '4px',
              }}
            >
              SALE
            </Box>

            {/* Product info */}
            <Box p="3" clearfix>
              <Title size="5" mb="2" interaction="unselectable">
                Premium Product
              </Title>

              <Content float="left" style={{ width: '60%' }} overflow="clipped">
                This is a detailed product description that might be quite long
                but will be clipped if it exceeds the container width.
              </Content>

              <Box float="right" textAlign="right">
                <Content mb="2" interaction="unselectable">
                  $99.99
                </Content>
                <Button
                  color="primary"
                  interaction="clickable"
                  shadow="shadowless"
                  radius="radiusless"
                >
                  Add to Cart
                </Button>
              </Box>
            </Box>
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Best Practices

:::tip Other Helpers Guidelines

1. **Use sparingly**: These helpers solve specific problems - don't overuse them
2. **Combine thoughtfully**: Many helpers work well together but consider the overall design
3. **Consider accessibility**: Some helpers like `unselectable` can impact accessibility
4. **Test interactions**: Always test clickable elements and overlays across different devices
5. **Use semantic markup**: Combine helpers with appropriate semantic HTML elements

:::

### Common Patterns

```tsx
// Modal backdrop
<Box overlay={true} backgroundColor="dark" style={{ opacity: 0.5 }} />

// Clickable card
<Card interaction="clickable" onClick={handleClick}>
  <Card.Content interaction="unselectable">
    Non-selectable content
  </Card.Content>
</Card>

// Image gallery item with positioning
<Box relative>
  <Image src="..." radius="radiusless" />
  <Box overlay={true} interaction="clickable" onClick={openLightbox} />
</Box>

// Floating action button
<Button
  color="primary"
  radius="radiusless"
  shadow="shadowless"
  style={{ position: 'fixed', bottom: '20px', right: '20px' }}
>
  +
</Button>

// Layout with floated sidebar and clearfix
<Box clearfix>
  <Box float="left" style={{ width: '200px' }}>
    Sidebar content
  </Box>
  <Box style={{ marginLeft: '220px' }}>
    Main content area
  </Box>
</Box>
```

:::tip Learn More

For detailed API information about available helper properties, see the [useBulmaClasses API documentation](/docs/api/helpers/usebulmaclasses).

:::

## See Also

- [useBulmaClasses](/docs/api/helpers/usebulmaclasses) - Complete helper property reference
- [Flexbox Helpers](/docs/guides/helpers/flex) - Flexbox layout utilities
- [Visibility Helpers](/docs/guides/helpers/visibility) - Display and visibility utilities
- [Typography Helpers](/docs/guides/helpers/typography) - Text styling utilities
- [Bulma Other Helpers Documentation](https://bulma.io/documentation/helpers/other-helpers/) - Official Bulma other helpers

---

## Typography


Bulma provides comprehensive typography helpers to control text size, alignment, transformation, weight, and font family. These utilities ensure consistent typography throughout your application.

:::tip Composable hook

These props are also available standalone via the `useTypographyClasses` hook — see [Composable Mini-Hooks](/docs/api/helpers/usebulmaclasses#composable-mini-hooks).

:::

:::info Reference

This page documents the bestax-bulma prop API for Bulma's typography helpers. For the underlying CSS utilities, see the [official Bulma typography helpers](https://bulma.io/documentation/helpers/typography-helpers/).

:::

:::tip

All components in bestax-bulma have access to these typography properties through the `useBulmaClasses` hook. You can apply typography properties to any component in the library.

:::

## Size

Control text size using the `textSize` prop. Bulma provides 7 size levels with size 1 being the largest and size 7 being the smallest.

| Property       | Bulma Class | Value          |
| -------------- | ----------- | -------------- |
| `textSize="1"` | `is-size-1` | 3rem (48px)    |
| `textSize="2"` | `is-size-2` | 2.5rem (40px)  |
| `textSize="3"` | `is-size-3` | 2rem (32px)    |
| `textSize="4"` | `is-size-4` | 1.5rem (24px)  |
| `textSize="5"` | `is-size-5` | 1.25rem (20px) |
| `textSize="6"` | `is-size-6` | 1rem (16px)    |
| `textSize="7"` | `is-size-7` | 0.75rem (12px) |

### Size Examples

```tsx live

function SizeExamples() {
  return (
    <Box p="4">
      <Content textSize="1" mb="3">
        Size 1 - Largest (3rem)
      </Content>
      <Content textSize="2" mb="3">
        Size 2 - Very Large (2.5rem)
      </Content>
      <Content textSize="3" mb="3">
        Size 3 - Large (2rem)
      </Content>
      <Content textSize="4" mb="3">
        Size 4 - Medium Large (1.5rem)
      </Content>
      <Content textSize="5" mb="3">
        Size 5 - Medium (1.25rem)
      </Content>
      <Content textSize="6" mb="3">
        Size 6 - Normal (1rem)
      </Content>
      <Content textSize="7" mb="3">
        Size 7 - Small (0.75rem)
      </Content>
    </Box>
  );
}
```

## Responsive Size

You can apply responsive text sizes that change based on screen size using the `viewport` prop combined with `textSize`.

### Responsive Breakpoints

| Viewport                | Screen Size               | Description         |
| ----------------------- | ------------------------- | ------------------- |
| `viewport="mobile"`     | Up to 768px               | Mobile devices      |
| `viewport="tablet"`     | Between 769px and 1023px  | Tablet devices      |
| `viewport="desktop"`    | Between 1024px and 1215px | Desktop screens     |
| `viewport="widescreen"` | Between 1216px and 1407px | Widescreen displays |
| `viewport="fullhd"`     | 1408px and above          | Full HD and larger  |

### Viewport-Specific Text Size Props

For combining multiple viewports on a single element, use these per-viewport props instead of `viewport` + `textSize`. Each accepts values `'1'` through `'7'`.

| Property             | Bulma Class Pattern      | Target Viewport  |
| -------------------- | ------------------------ | ---------------- |
| `textSizeMobile`     | `is-size-{n}-mobile`     | Up to 768px      |
| `textSizeTablet`     | `is-size-{n}-tablet`     | 769px – 1023px   |
| `textSizeDesktop`    | `is-size-{n}-desktop`    | 1024px – 1215px  |
| `textSizeWidescreen` | `is-size-{n}-widescreen` | 1216px – 1407px  |
| `textSizeFullhd`     | `is-size-{n}-fullhd`     | 1408px and above |

### Responsive Size Examples

```tsx live

function ResponsiveSizeExample() {
  return (
    <Box p="4">
      <Title textSizeMobile="2" textSizeDesktop="1" mb="4">
        Responsive Heading
      </Title>

      <Content textSizeMobile="5" textSizeTablet="4" textSizeDesktop="3">
        This text gets larger on bigger screens: size 5 on mobile, size 4 on
        tablet, and size 3 on desktop.
      </Content>
    </Box>
  );
}
```

## Alignment

Control text alignment using the `textAlign` prop.

| Property                | Bulma Class          | Value          |
| ----------------------- | -------------------- | -------------- |
| `textAlign="left"`      | `has-text-left`      | Left aligned   |
| `textAlign="centered"`  | `has-text-centered`  | Center aligned |
| `textAlign="right"`     | `has-text-right`     | Right aligned  |
| `textAlign="justified"` | `has-text-justified` | Justified      |

### Alignment Examples

```tsx live

function AlignmentExamples() {
  return (
    <Box p="4">
      <Content
        textAlign="left"
        mb="3"
        backgroundColor="light"
        color="dark"
        p="3"
      >
        Left aligned text - This text is aligned to the left side of the
        container.
      </Content>

      <Content
        textAlign="centered"
        mb="3"
        backgroundColor="light"
        color="dark"
        p="3"
      >
        Centered text - This text is centered within the container.
      </Content>

      <Content
        textAlign="right"
        mb="3"
        backgroundColor="light"
        color="dark"
        p="3"
      >
        Right aligned text - This text is aligned to the right side of the
        container.
      </Content>

      <Content textAlign="justified" backgroundColor="light" color="dark" p="3">
        Justified text - This longer text is justified, which means it spreads
        out to fill the entire width of the container, creating straight edges
        on both sides by adjusting the spacing between words.
      </Content>
    </Box>
  );
}
```

## Responsive Alignment

Apply responsive text alignment that changes based on screen size.

### Viewport-Specific Text Align Props

Like the text size viewport props, these per-viewport alignment props can be combined on one element. Each accepts `'centered'`, `'justified'`, `'left'`, or `'right'`.

| Property              | Bulma Class Pattern           | Target Viewport  |
| --------------------- | ----------------------------- | ---------------- |
| `textAlignMobile`     | `has-text-{value}-mobile`     | Up to 768px      |
| `textAlignTablet`     | `has-text-{value}-tablet`     | 769px – 1023px   |
| `textAlignDesktop`    | `has-text-{value}-desktop`    | 1024px – 1215px  |
| `textAlignWidescreen` | `has-text-{value}-widescreen` | 1216px – 1407px  |
| `textAlignFullhd`     | `has-text-{value}-fullhd`     | 1408px and above |

### Responsive Alignment Examples

```tsx live

function ResponsiveAlignmentExample() {
  return (
    <Box p="4">
      <Title textAlignMobile="centered" textAlignDesktop="left" mb="4">
        Responsive Alignment
      </Title>

      <Content
        textAlignMobile="centered"
        textAlignTablet="left"
        textAlignDesktop="justified"
      >
        This text is centered on mobile, left-aligned on tablet, and justified
        on desktop screens. Resize your browser to see the changes.
      </Content>
    </Box>
  );
}
```

## Text Transformation

Control text transformation using the `textTransform` prop.

| Property                      | Bulma Class      | Value                                |
| ----------------------------- | ---------------- | ------------------------------------ |
| `textTransform="capitalized"` | `is-capitalized` | Capitalize first letter of each word |
| `textTransform="lowercase"`   | `is-lowercase`   | All lowercase                        |
| `textTransform="uppercase"`   | `is-uppercase`   | ALL UPPERCASE                        |
| `textTransform="italic"`      | `is-italic`      | Italic text                          |

### Text Transformation Examples

```tsx live

function TextTransformExamples() {
  return (
    <Box p="4">
      <Content textTransform="capitalized" mb="3">
        capitalized text - Each Word Is Capitalized
      </Content>

      <Content textTransform="lowercase" mb="3">
        LOWERCASE TEXT - all letters become lowercase
      </Content>

      <Content textTransform="uppercase" mb="3">
        uppercase text - ALL LETTERS BECOME UPPERCASE
      </Content>

      <Content textTransform="italic">
        Italic text - This text appears in italics
      </Content>
    </Box>
  );
}
```

## Text Weight

Control font weight using the `textWeight` prop.

| Property                | Bulma Class                | Value                |
| ----------------------- | -------------------------- | -------------------- |
| `textWeight="light"`    | `has-text-weight-light`    | 300 weight           |
| `textWeight="normal"`   | `has-text-weight-normal`   | 400 weight (default) |
| `textWeight="medium"`   | `has-text-weight-medium`   | 500 weight           |
| `textWeight="semibold"` | `has-text-weight-semibold` | 600 weight           |
| `textWeight="bold"`     | `has-text-weight-bold`     | 700 weight           |

### Text Weight Examples

```tsx live

function TextWeightExamples() {
  return (
    <Box p="4">
      <Content textWeight="light" textSize="4" mb="3">
        Light weight text (300)
      </Content>

      <Content textWeight="normal" textSize="4" mb="3">
        Normal weight text (400)
      </Content>

      <Content textWeight="medium" textSize="4" mb="3">
        Medium weight text (500)
      </Content>

      <Content textWeight="semibold" textSize="4" mb="3">
        Semibold weight text (600)
      </Content>

      <Content textWeight="bold" textSize="4">
        Bold weight text (700)
      </Content>
    </Box>
  );
}
```

## Font Family

Control font family using the `fontFamily` prop.

| Property                  | Bulma Class            | Value                                |
| ------------------------- | ---------------------- | ------------------------------------ |
| `fontFamily="sans-serif"` | `is-family-sans-serif` | Sans-serif font stack                |
| `fontFamily="monospace"`  | `is-family-monospace`  | Monospace font stack                 |
| `fontFamily="primary"`    | `is-family-primary`    | Primary font family                  |
| `fontFamily="secondary"`  | `is-family-secondary`  | Secondary font family                |
| `fontFamily="code"`       | `is-family-code`       | Code font family (usually monospace) |

### Font Family Examples

```tsx live

function FontFamilyExamples() {
  return (
    <Box p="4">
      <Content fontFamily="sans-serif" mb="3">
        Sans-serif font family - Clean, modern appearance without serifs
      </Content>

      <Content fontFamily="monospace" mb="3">
        Monospace font family - Each character takes the same width
      </Content>

      <Content fontFamily="primary" mb="3">
        Primary font family - The primary font defined in your theme
      </Content>

      <Content fontFamily="secondary" mb="3">
        Secondary font family - The secondary font defined in your theme
      </Content>

      <Content fontFamily="code">
        Code font family - Optimized for displaying code snippets
      </Content>
    </Box>
  );
}
```

## Combined Typography

Create sophisticated typography by combining multiple typography properties:

```tsx live

function CombinedTypographyExample() {
  return (
    <Box p="4">
      <Card p="6">
        <Card.Content>
          <Title
            textSize="1"
            textAlign="centered"
            textWeight="bold"
            color="primary"
            mb="3"
          >
            Main Heading
          </Title>

          <SubTitle
            textSize="4"
            textAlign="centered"
            textWeight="light"
            color="grey"
            textTransform="uppercase"
            mb="5"
          >
            Article Subtitle
          </SubTitle>

          <Content
            textSize="5"
            textAlign="justified"
            textWeight="normal"
            fontFamily="primary"
            mb="4"
          >
            This is the main content paragraph with justified alignment and
            normal weight. It demonstrates how multiple typography properties
            can be combined to create sophisticated text layouts.
          </Content>

          <Content
            textSize="6"
            textAlign="right"
            textWeight="medium"
            textTransform="italic"
            color="grey-dark"
            fontFamily="secondary"
          >
            — Author Name, Publication Date
          </Content>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Article Layout Example

Here's a comprehensive example showing typography in an article layout:

```tsx live
// import {
//   Title,
//   SubTitle,
//   Content,
//   Box,
//   Section,
//   Container,
// } from '@allxsmith/bestax-bulma';

function ArticleExample() {
  return (
    <Section py="6">
      <Container>
        <Box maxWidth="800px" mx="auto">
          {/* Article Header */}
          <Title textSize="1" textWeight="bold" textAlign="centered" mb="3">
            The Future of Web Typography
          </Title>

          <SubTitle
            textSize="5"
            textWeight="normal"
            textAlign="centered"
            color="grey"
            mb="2"
          >
            Exploring modern approaches to web fonts and text layout
          </SubTitle>

          <Content
            textSize="7"
            textAlign="centered"
            textTransform="uppercase"
            color="grey-light"
            textWeight="medium"
            mb="6"
          >
            Published March 15, 2024
          </Content>

          {/* Article Body */}
          <Content textSize="5" textAlign="justified" mb="4">
            Typography is the art and technique of arranging type to make
            written language legible, readable, and appealing when displayed. In
            web development, good typography enhances user experience and
            communicates your brand's personality.
          </Content>

          <Content textSize="5" textAlign="justified" mb="4">
            With the evolution of CSS and web fonts, developers now have
            unprecedented control over typography. From variable fonts to
            advanced CSS features, the possibilities are endless.
          </Content>

          {/* Pull Quote */}
          <Box
            backgroundColor="light"
            p="4"
            my="5"
            borderLeft="4px solid"
            borderColor="primary"
          >
            <Content
              textSize="4"
              textWeight="medium"
              textAlign="centered"
              textTransform="italic"
              color="primary"
            >
              "Typography is the craft of endowing human language with a durable
              visual form."
            </Content>
          </Box>

          <Content textSize="5" textAlign="justified">
            As we continue to push the boundaries of web design, typography
            remains a fundamental pillar of effective communication and
            beautiful user interfaces.
          </Content>
        </Box>
      </Container>
    </Section>
  );
}
```

:::tip Learn More

For detailed API information about typography properties, see the [useBulmaClasses API documentation](/docs/api/helpers/usebulmaclasses).

:::

## See Also

- [useBulmaClasses](/docs/api/helpers/usebulmaclasses) - Complete typography property reference
- [Responsive Design](/docs/guides/features/responsiveness) - Responsive typography techniques
- [Color Helpers](/docs/guides/helpers/color) - Text color properties
- [Title & SubTitle Components](/docs/api/elements/title) - Dedicated heading components
- [Bulma Typography Documentation](https://bulma.io/documentation/helpers/typography-helpers/) - Official Bulma typography helpers

---

## Visibility


Bulma provides comprehensive visibility helpers to control how elements are displayed and hidden across different screen sizes and contexts. These utilities are essential for responsive design and accessibility.

:::tip Composable hook

These props are also available standalone via the `useVisibilityClasses` hook — see [Composable Mini-Hooks](/docs/api/helpers/usebulmaclasses#composable-mini-hooks).

:::

:::info Reference

This page documents the bestax-bulma prop API for Bulma's visibility helpers. For the underlying CSS utilities, see the [official Bulma visibility helpers](https://bulma.io/documentation/helpers/visibility-helpers/).

:::

:::tip

All components in bestax-bulma have access to these visibility properties through the `useBulmaClasses` hook. You can apply visibility properties to any component in the library.

:::

## Display

Control the CSS display property using the `display` prop or viewport-specific display properties. This determines how an element is displayed in the document flow.

### Basic Display Properties

| Property                 | Bulma Class       | Description                                |
| ------------------------ | ----------------- | ------------------------------------------ |
| `display="block"`        | `is-block`        | Block-level element (full width, new line) |
| `display="flex"`         | `is-flex`         | Flexbox container                          |
| `display="inline"`       | `is-inline`       | Inline element (flows with text)           |
| `display="inline-block"` | `is-inline-block` | Inline element that can have width/height  |
| `display="inline-flex"`  | `is-inline-flex`  | Inline flexbox container                   |
| `display="none"`         | `is-hidden`       | Element is completely hidden               |

### Viewport-Specific Display Properties

For responsive layouts requiring different display types across viewports, use the viewport-specific display properties:

| Property            | Bulma Class Pattern       | Target Viewport  | Description                     |
| ------------------- | ------------------------- | ---------------- | ------------------------------- |
| `displayMobile`     | `is-{display}-mobile`     | Up to 768px      | Display type on mobile devices  |
| `displayTablet`     | `is-{display}-tablet`     | 769px - 1023px   | Display type on tablet devices  |
| `displayDesktop`    | `is-{display}-desktop`    | 1024px - 1215px  | Display type on desktop screens |
| `displayWidescreen` | `is-{display}-widescreen` | 1216px - 1407px  | Display type on widescreen      |
| `displayFullhd`     | `is-{display}-fullhd`     | 1408px and above | Display type on fullHD+         |

**Example:** `displayMobile="flex"` generates `is-flex-mobile`, `displayDesktop="none"` generates `is-hidden-desktop`

:::tip

Use viewport-specific display properties when you need different display behaviors across multiple screen sizes. The generic `display` + `viewport` pattern only supports one viewport combination at a time.

:::

### Display Examples

```tsx live

function DisplayExamples() {
  return (
    <Box p="4">
      <Content mb="4">
        Block Display: Takes full width and starts on a new
        line
      </Content>
      <Box
        display="block"
        backgroundColor="primary"
        textColor="white"
        p="2"
        mb="3"
      >
        Block element
      </Box>

      <Content mb="4">
        Inline Display: Flows with the text content
      </Content>
      
        Here is some text with an
        <Box display="inline" backgroundColor="info" textColor="white" px="2">
          inline element
        </Box>
        in the middle of the sentence.
      

      <Content mb="4" mt="4">
        Inline-block Display: Inline but can have dimensions
      </Content>
      
        Text with
        <Box
          display="inline-block"
          backgroundColor="success"
          textColor="white"
          p="2"
          mr="1"
        >
          inline-block
        </Box>
        elements that can have padding and margins.
      

      <Content mb="4" mt="4">
        Flex Display: Creates a flex container
      </Content>
      <Box display="flex" mb="3">
        <Button color="primary" mr="3">
          Flex Item 1
        </Button>
        <Button color="info" mr="3">
          Flex Item 2
        </Button>
        <Button color="success">Flex Item 3</Button>
      </Box>

      <Content mb="4">
        Inline-flex Display: Inline flex container
      </Content>
      
        Text with
        <Box display="inline-flex">
          <Button size="small" color="warning" mr="2">
            A
          </Button>
          <Button size="small" color="danger">
            B
          </Button>
        </Box>
        inline flex elements.
      
    </Box>
  );
}
```

### Viewport-Specific Display Examples

```tsx live

function ViewportDisplayExamples() {
  return (
    <Box p="4">
      <Notification color="info" mb="4">
        Resize your browser window to see elements change their display type at
        different screen sizes.
      </Notification>

      <Content mb="4">
        Progressive Display Changes: Different display types
        across viewports
      </Content>
      <Box
        displayMobile="block"
        displayTablet="inline-block"
        displayDesktop="flex"
        p="3"
        mb="3"
      >
        <Notification color="primary" mb="2">
          Mobile: block | Tablet: inline-block | Desktop+: flex
        </Notification>
        <Notification color="link" mb="2">
          Item 2 (flex layout on desktop+)
        </Notification>
      </Box>

      <Content mb="4">
        Mobile Hidden, Desktop Visible: Show/hide across
        viewports
      </Content>
      <Box displayMobile="none" displayDesktop="block" mb="3">
        <Notification color="success">
          📱 Hidden on mobile/tablet, visible on desktop and larger
        </Notification>
      </Box>

      <Content mb="4">
        Responsive Flex Layout: Block on mobile, flex on larger
        screens
      </Content>
      <Box displayMobile="block" displayTablet="flex" p="3" mb="3">
        <Notification color="warning" mr="2" mb="2">
          Stacked on mobile
        </Notification>
        <Notification color="danger" mr="2" mb="2">
          Side-by-side on tablet+
        </Notification>
        <Notification color="info" mb="2">
          Responsive layout
        </Notification>
      </Box>
    </Box>
  );
}
```

## Show/Hide Elements

Control element visibility across different screen sizes using responsive display helpers. You can show or hide elements on specific viewports using either the generic pattern or viewport-specific properties.

### Generic Display + Viewport Pattern

For simple show/hide scenarios affecting a single viewport, use the `display` + `viewport` combination:

```tsx live
<>
  Show only on desktop and larger
  <Box display="block" viewport="desktop">
    Desktop+ only content
  </Box>
  Hide only on mobile
  <Box display="none" viewport="mobile">
    Hidden on mobile
  </Box>
</>
```

:::warning Limitation

The generic `display` + `viewport` pattern only supports **one viewport combination** at a time. You cannot chain multiple display/viewport pairs on the same element.

:::

### Viewport-Specific Properties (Recommended)

For complex responsive behavior requiring different display types across multiple viewports, use the viewport-specific display properties:

```tsx live

function ViewportSpecificExample() {
  return (
    <Box p="4">
      <Box
        displayMobile="none"
        displayTablet="block"
        displayDesktop="flex"
        backgroundColor="primary"
        color="white"
        p="3"
      >
        Hide on mobile, show as block on tablet, flex on desktop+
      </Box>
    </Box>
  );
}
```

## Choosing the Right Approach

### When to Use Generic Display + Viewport

✅ **Use when you need simple single-viewport control:**

```tsx live

function GenericDisplayExample() {
  return (
    <Box p="4">
      <Box
        display="none"
        viewport="mobile"
        backgroundColor="warning"
        textColor="dark"
        p="3"
        mb="3"
      >
        Hidden on mobile only
      </Box>
      <Box
        display="block"
        viewport="desktop"
        backgroundColor="success"
        textColor="white"
        p="3"
      >
        Desktop and up only
      </Box>
    </Box>
  );
}
```

### When to Use Viewport-Specific Properties

✅ **Use when you need multiple viewport behaviors:**

```tsx live

function MultipleViewportExample() {
  return (
    <Box p="4">
      <Box
        displayMobile="none"
        displayTablet="block"
        displayDesktop="flex"
        p="3"
        mb="3"
      >
        <Notification color="primary" mr="2" mb="2">
          Different displays across multiple viewports
        </Notification>
        <Notification color="info" mb="2">
          Hidden on mobile, block on tablet, flex on desktop
        </Notification>
      </Box>

      <Box
        displayMobile="block"
        displayTablet="inline-block"
        displayDesktop="flex"
        p="3"
      >
        <Notification color="success" mr="2" mb="2">
          Progressive layout enhancement
        </Notification>
        <Notification color="warning" mb="2">
          Stacked → inline-block → flex
        </Notification>
      </Box>
    </Box>
  );
}
```

:::info Precedence Rule

When both patterns are used together, **viewport-specific properties take precedence** over the generic `display` + `viewport` combination.

```tsx live

function PrecedenceExample() {
  return (
    <Box p="4">
      <Box
        display="block"
        viewport="mobile"
        displayMobile="flex"
        backgroundColor="danger"
        color="white"
        p="3"
      >
        Will be flex on mobile, not block (viewport-specific wins!)
      </Box>
    </Box>
  );
}
```

:::

### Responsive Show/Hide Examples

```tsx live

function ResponsiveShowHideExamples() {
  return (
    <Box p="4">
      <Notification color="info" mb="4">
        Resize your browser window to see elements appear and disappear at
        different screen sizes.
      </Notification>

      <Content mb="4">
        Mobile Only: Visible only on mobile devices
      </Content>
      <Box
        displayMobile="block"
        displayTablet="none"
        backgroundColor="primary"
        color="white"
        p="3"
        mb="3"
      >
        📱 Visible only on mobile (up to 768px)
      </Box>

      <Content mb="4">
        Tablet Only: Visible only on tablet devices
      </Content>
      <Box
        displayMobile="none"
        displayTablet="block"
        displayDesktop="none"
        backgroundColor="info"
        color="white"
        p="3"
        mb="3"
      >
        📱 Visible only on tablet (769px - 1023px)
      </Box>

      <Content mb="4">
        Desktop Only: Visible only on desktop screens
      </Content>
      <Box
        displayMobile="none"
        displayTablet="none"
        displayDesktop="block"
        displayWidescreen="none"
        backgroundColor="success"
        color="white"
        p="3"
        mb="3"
      >
        💻 Visible only on desktop (1024px - 1215px)
      </Box>

      <Content mb="4">
        Widescreen Only: Visible only on widescreen displays
      </Content>
      <Box
        displayDesktop="none"
        displayWidescreen="block"
        displayFullhd="none"
        backgroundColor="warning"
        color="dark"
        p="3"
        mb="3"
      >
        🖥️ Visible only on widescreen (1216px - 1407px)
      </Box>

      <Content mb="4">
        FullHD Only: Visible only on fullHD displays
      </Content>
      <Box
        displayWidescreen="none"
        displayFullhd="block"
        backgroundColor="danger"
        color="white"
        p="3"
        mb="3"
      >
        🖥️ Visible only on fullHD (1408px and above)
      </Box>

      <Content mb="4">
        Show from Breakpoint Up: Hidden on mobile, visible from
        tablet and up
      </Content>
      <Box
        displayMobile="none"
        displayTablet="block"
        backgroundColor="grey"
        color="white"
        p="3"
        mb="3"
      >
        📱→🖥️ Hidden on mobile, visible from tablet and up
      </Box>

      <Content mb="4">
        Show up to Breakpoint: Visible on mobile and tablet,
        hidden from desktop up
      </Content>
      <Box
        displayMobile="block"
        displayTablet="block"
        displayDesktop="none"
        backgroundColor="black"
        color="white"
        p="3"
      >
        📱📱 Visible on mobile and tablet, hidden from desktop up
      </Box>
    </Box>
  );
}
```

## Hide

Control element hiding across different screen sizes using the `visibility` prop or viewport-specific display properties. This is useful for responsive design where you want to hide content on specific screen sizes.

### Hide Examples

```tsx live

function HideExamples() {
  return (
    <Box p="4">
      <Title size="4" mb="4">
        Responsive Hide Examples
      </Title>

      <Card mb="4">
        <Card.Content>
          <Title size="5" mb="3">
            Navigation Menu
          </Title>

          {/* Desktop navigation - hidden on mobile */}
          <Box displayMobile="none" displayTablet="flex" mb="3">
            <Button variant="text" mr="3">
              Home
            </Button>
            <Button variant="text" mr="3">
              About
            </Button>
            <Button variant="text" mr="3">
              Services
            </Button>
            <Button variant="text">Contact</Button>
          </Box>

          {/* Mobile menu button - hidden on tablet+ */}
          <Button displayMobile="block" displayTablet="none" color="primary">
            ☰ Menu
          </Button>

          <Content>
            This demonstrates a responsive navigation where full menu links are
            shown on larger screens, but only a menu button is shown on mobile.
          </Content>
        </Card.Content>
      </Card>

      <Card mb="4">
        <Card.Content>
          <Title size="5" mb="3">
            Content Layout
          </Title>

          <Box display="flex">
            <Box style={{ flex: 1, marginRight: '1rem' }}>
              <Content>
                This is the main content area that's always visible.
              </Content>
            </Box>

            {/* Sidebar hidden on mobile */}
            <Box
              displayMobile="none"
              displayTablet="block"
              backgroundColor="light"
              textColor="dark"
              p="3"
              style={{ width: '200px' }}
            >
              <Title size="6" mb="2" textColor="dark">
                Sidebar
              </Title>
              <Content textSize="7">
                This sidebar is hidden on mobile devices but visible on tablet
                and larger screens.
              </Content>
            </Box>
          </Box>
        </Card.Content>
      </Card>

      <Card>
        <Card.Content>
          <Title size="5" mb="3">
            Progressive Content Reveal
          </Title>

          <Content mb="3">
            Basic information visible on all screen sizes.
          </Content>

          {/* Additional details hidden on mobile */}
          <Box
            displayMobile="none"
            displayTablet="block"
            backgroundColor="info"
            color="white"
            p="3"
            mb="3"
          >
            Additional details visible on tablet and larger screens.
          </Box>

          {/* Extended content hidden on mobile and tablet */}
          <Box
            displayMobile="none"
            displayTablet="none"
            displayDesktop="block"
            backgroundColor="success"
            color="white"
            p="3"
          >
            Extended content only visible on desktop and larger screens.
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Other Visibility Properties

Additional visibility utilities for specific use cases.

| Property                 | Bulma Class    | Description                               |
| ------------------------ | -------------- | ----------------------------------------- |
| `visibility="hidden"`    | `is-hidden`    | Element is not visible but takes up space |
| `visibility="sr-only"`   | `is-sr-only`   | Only visible to screen readers            |
| `visibility="invisible"` | `is-invisible` | Element is invisible but takes up space   |

### Viewport-Specific Visibility Properties

Each visibility value (`'hidden'`, `'sr-only'`, `'invisible'`) can be scoped to a specific breakpoint using these viewport-specific props. Unlike the generic `visibility` + `viewport` pair, these can be combined on a single element to describe different behavior per viewport.

| Property               | Bulma Class Pattern     | Target Viewport  |
| ---------------------- | ----------------------- | ---------------- |
| `visibilityMobile`     | `is-{value}-mobile`     | Up to 768px      |
| `visibilityTablet`     | `is-{value}-tablet`     | 769px – 1023px   |
| `visibilityDesktop`    | `is-{value}-desktop`    | 1024px – 1215px  |
| `visibilityWidescreen` | `is-{value}-widescreen` | 1216px – 1407px  |
| `visibilityFullhd`     | `is-{value}-fullhd`     | 1408px and above |

**Example:** `visibilityMobile="hidden"` generates `is-hidden-mobile`; `visibilityDesktop="invisible"` generates `is-invisible-desktop`.

```tsx live
<Box
  visibilityMobile="hidden"
  visibilityDesktop="invisible"
  backgroundColor="warning"
  p="3"
>
  Hidden on mobile, invisible on desktop and up, visible on tablet.
</Box>
```

### Other Visibility Examples

```tsx live

function OtherVisibilityExamples() {
  return (
    <Box p="4">
      <Title size="4" mb="4">
        Other Visibility Properties
      </Title>

      <Content mb="4">
        Hidden vs Invisible: Both make elements not visible,
        but they still take up space in the layout.
      </Content>

      <Box display="flex" mb="4">
        <Button color="primary" mr="3">
          Visible Button
        </Button>
        <Button visibility="hidden" color="info" mr="3">
          Hidden Button
        </Button>
        <Button color="success">Another Visible Button</Button>
      </Box>

      <Box display="flex" mb="4">
        <Button color="primary" mr="3">
          Visible Button
        </Button>
        <Button visibility="invisible" color="warning" mr="3">
          Invisible Button
        </Button>
        <Button color="danger">Another Visible Button</Button>
      </Box>

      <Content mb="4">
        Screen Reader Only: Content that's only accessible to
        screen readers for better accessibility.
      </Content>

      <Box>
        <Icon name="star" ariaLabel="Star rating" />
        This product has a 5-star rating
        <Icon name="star" ariaLabel="Star rating" />
        out of 5 stars
        <Icon name="star" ariaLabel="Star rating" />
      </Box>

      <Content mt="4" textSize="7" color="grey">
        The text between the stars is only visible to screen readers, providing
        context for users with visual impairments.
      </Content>
    </Box>
  );
}
```

## Accessibility Considerations

:::info

When hiding content, consider the accessibility implications:

- **`visibility="hidden"`**: Content is not visible and not accessible to screen readers
- **`visibility="invisible"`**: Content is not visible but takes up space and is not accessible to screen readers
- **`visibility="sr-only"`**: Content is only accessible to screen readers - use this for important context
- **`display="none"`**: Content is completely removed from the document flow and accessibility tree

:::

### Accessible Hide/Show Example

```tsx live

function AccessibleToggleExample() {
  const [isExpanded, setIsExpanded] = useState(false);

  return (
    <Box p="4">
      <Card>
        <Card.Content>
          <Box
            display="flex"
            justifyContent="space-between"
            alignItems="center"
            mb="3"
          >
            <Title size="5">Expandable Content</Title>
            <Button
              color="primary"
              size="small"
              onClick={() => setIsExpanded(!isExpanded)}
            >
              {isExpanded ? 'Hide' : 'Show'} Details
            </Button>
          </Box>

          <Content>
            This is always visible content that provides context.
          </Content>

          {/* Screen reader announcement */}
          
            {isExpanded
              ? 'Additional details are now visible'
              : 'Additional details are hidden'}
          

          {/* Expandable content */}
          <Box
            display={isExpanded ? 'block' : 'none'}
            mt="3"
            backgroundColor="light"
            textColor="dark"
            p="3"
          >
            <Content>
              This additional content can be toggled on and off. The
              implementation ensures that screen readers are properly informed
              about the state changes.
            </Content>
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

## Mobile-First Responsive Design

:::tip Best Practice

Use a mobile-first approach where you design for mobile by default, then progressively enhance for larger screens using viewport-specific display helpers.

:::

```tsx live

function MobileFirstExample() {
  return (
    <Box p="4">
      <Card>
        <Card.Content>
          {/* Mobile layout by default */}
          <Title size="4" textAlign="centered" mb="4">
            Mobile-First Design
          </Title>

          {/* Stack vertically on mobile, horizontal on tablet+ */}
          <Box displayMobile="block" displayTablet="flex">
            <Box style={{ flex: 1, marginRight: '1rem' }}>
              <Content>
                This content stacks vertically on mobile and displays
                horizontally on tablet and larger screens.
              </Content>
            </Box>

            <Box style={{ flex: 1 }}>
              <Content>
                The spacing and layout automatically adapts to different screen
                sizes using viewport-specific display utilities.
              </Content>
            </Box>
          </Box>

          {/* Simple mobile menu, complex desktop menu */}
          <Box mt="4">
            {/* Mobile: Simple button */}
            <Button
              displayMobile="block"
              displayTablet="none"
              color="primary"
              fullWidth
            >
              Mobile Actions
            </Button>

            {/* Desktop: Multiple buttons */}
            <Box
              displayMobile="none"
              displayTablet="flex"
              justifyContent="center"
            >
              <Button color="primary" mr="2">
                Save
              </Button>
              <Button color="info" mr="2">
                Edit
              </Button>
              <Button color="warning" mr="2">
                Share
              </Button>
              <Button variant="outlined">Cancel</Button>
            </Box>
          </Box>

          {/* Progressive content enhancement */}
          <Box mt="4">
            <Content>Basic content visible on all devices.</Content>

            <Box
              displayMobile="none"
              displayTablet="block"
              backgroundColor="light"
              textColor="dark"
              p="3"
              mt="2"
            >
              <Content textSize="7">
                Enhanced content for tablet and larger screens with additional
                context and details.
              </Content>
            </Box>

            <Box
              displayMobile="none"
              displayDesktop="block"
              backgroundColor="primary"
              color="white"
              p="3"
              mt="2"
            >
              <Content textSize="7">
                Premium content only shown on desktop and larger screens where
                there's ample space.
              </Content>
            </Box>
          </Box>
        </Card.Content>
      </Card>
    </Box>
  );
}
```

:::tip Learn More

For detailed API information about visibility properties, see the [useBulmaClasses API documentation](/docs/api/helpers/usebulmaclasses).

:::

## See Also

- [useBulmaClasses](/docs/api/helpers/usebulmaclasses) - Complete visibility property reference
- [Responsive Design](/docs/guides/features/responsiveness) - Responsive design principles

<!--
- [Flexbox Helpers](/docs/guides/helpers/flex) - Flex display and layout utilities
- [Display Utilities](/docs/api/helpers/display) - Additional display helper utilities
-->

- [Bulma Visibility Documentation](https://bulma.io/documentation/helpers/visibility-helpers/) - Official Bulma visibility helpers

---

## Columns Components Overview

# Columns Components

This page summarizes the Bulma-styled columns system in Bestax, with a brief description, usage example, and links to full documentation for each. Use these components to build responsive, flexible, and declarative grid layouts.

---

## Columns

A responsive grid container for aligning and distributing `Column` components. Supports wrapping, gap control, centering, vertical alignment, responsive breakpoints, and all Bulma/utility helper props.

:::info
Use `Columns` as the parent for all column-based layouts. It handles responsive wrapping and spacing automatically.
:::

```tsx live
<Columns>
  <Column>
    <Notification color="primary">First column</Notification>
  </Column>
  <Column>
    <Notification color="info">Second column</Notification>
  </Column>
</Columns>
```

**Gapless Columns**

Remove the gap between columns using the `isGapless` prop. This is useful for tightly packed layouts.

:::tip
`isGapless` is great for dashboards or toolbars where you want columns to touch.
:::

```tsx live
<Columns isGapless>
  <Column>
    <Notification color="primary">No gap 1</Notification>
  </Column>
  <Column>
    <Notification color="info">No gap 2</Notification>
  </Column>
</Columns>
```

**Multiline Columns**

Allow columns to wrap to multiple lines using the `isMultiline` prop. This is helpful for responsive layouts with many columns.

:::caution
If you have more columns than fit in one row, use `isMultiline` to prevent overflow on small screens.
:::

```tsx live
<Columns isMultiline>
  <Column>
    <Notification color="primary">Column 1</Notification>
  </Column>
  <Column>
    <Notification color="info">Column 2</Notification>
  </Column>
  <Column>
    <Notification color="success">Column 3</Notification>
  </Column>
  <Column>
    <Notification color="warning">Column 4</Notification>
  </Column>
</Columns>
```

[View full documentation.](../../api/columns)

---

## Column

A single responsive layout column using Bulma's flexbox-based column system. Supports all Bulma column size modifiers, responsive sizes and offsets, color/background helpers, and narrow behavior. Use together with `Columns` for powerful, declarative layouts.

**Column Sizes**

Set the `size` prop to control the width of each column. You can use values like `"half"`, `"one-quarter"`, or numbers for fractional widths.

:::info
Mix and match column sizes for flexible layouts. Unspecified columns will auto-fill remaining space.
:::

```tsx live
<Columns>
  <Column size="half">
    <Notification color="primary">Half width</Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="info">One quarter</Notification>
  </Column>
  <Column>
    <Notification color="success">Auto width</Notification>
  </Column>
</Columns>
```

**Narrow Columns**

Use the `isNarrow` prop to make a column only as wide as its content.

:::tip
Narrow columns are perfect for buttons, icons, or small controls in a row.
:::

```tsx live
<Columns>
  <Column>
    <Notification color="primary">Normal</Notification>
  </Column>
  <Column isNarrow>
    <Notification color="warning">Narrow</Notification>
  </Column>
  <Column>
    <Notification color="info">Normal</Notification>
  </Column>
</Columns>
```

**Offset Columns**

Offset a column to add space before it using the `offset` prop.

:::caution
Offsets are useful for centering or right-aligning columns, but can cause layout issues if overused.
:::

```tsx live
<Columns>
  <Column>
    <Notification color="primary">First</Notification>
  </Column>
  <Column offset={2}>
    <Notification color="danger">Offset by 2</Notification>
  </Column>
</Columns>
```

[View full documentation.](../../api/columns/column)

---

For more details and advanced usage, see the full documentation for each component linked above.

---

## Components


The **Components** section provides higher-level, composable UI building blocks for your Bulma React applications. These components combine Bulma's styles and patterns with React flexibility, offering navigation, layout, feedback, and interactive controls. Each component supports Bulma's utility props for color, spacing, and accessibility, making it easy to build robust, consistent interfaces.

---

## Navigation

### Breadcrumb

A Bulma-styled breadcrumb navigation for showing the user's location in the app. [View full documentation.](../../api/components/breadcrumb.md)

```tsx live
<Breadcrumb>
  
    
      <Icon name="fas fa-home" ariaLabel="home icon" /> Home
    
  
  
    
      <Icon name="fas fa-folder" ariaLabel="category icon" /> Category
    
  
  
    
      <Icon name="fas fa-file" ariaLabel="item icon" /> Item
    
  
</Breadcrumb>
```

---

### Navbar

A responsive navigation bar with support for branding, menus, dropdowns, and more. [View full documentation.](../../api/components/navbar.md)

```tsx live
<Navbar>
  <Navbar.Brand>
    <Navbar.Item href="#">
      
    </Navbar.Item>
    <Navbar.Burger active={false} onClick={() => {}} />
  </Navbar.Brand>
  <Navbar.Menu active={false}>
    <Navbar.Start>
      <Navbar.Item href="#">Home</Navbar.Item>
      <Navbar.Item href="#">Docs</Navbar.Item>
      <Navbar.Item href="#">About</Navbar.Item>
    </Navbar.Start>
    <Navbar.End>
      <Navbar.Item href="#">Login</Navbar.Item>
    </Navbar.End>
  </Navbar.Menu>
</Navbar>
```

---

### Tabs

A flexible tab navigation system for switching between views or filtering content. [View full documentation.](../../api/components/tabs.md)

```tsx live
<Tabs align="centered">
  <Tabs.List>
    <Tabs.Item active>
      Home
    </Tabs.Item>
    <Tabs.Item>
      Profile
    </Tabs.Item>
    <Tabs.Item>
      Settings
    </Tabs.Item>
  </Tabs.List>
</Tabs>
```

---

### Steps

Multi-step progress indicator for wizard flows. Supports horizontal and vertical layouts with customizable markers. [View full documentation.](../../api/components/steps.md)

```tsx live
function StepsExample() {
  const [step, setStep] = React.useState(1);
  return (
    
      <Steps
        value={step}
        items={[
          { label: 'Account', clickable: true },
          { label: 'Profile', clickable: true },
          { label: 'Confirm', clickable: true },
        ]}
        onStepClick={setStep}
        color="primary"
      />
      
        <Button
          onClick={() => setStep(Math.max(0, step - 1))}
          disabled={step === 0}
        >
          Previous
        </Button>
        <Button
          onClick={() => setStep(Math.min(2, step + 1))}
          disabled={step === 2}
        >
          Next
        </Button>
      
    
  );
}
```

---

### Pagination

A flexible, composable pagination navigation for lists or multi-page content. [View full documentation.](../../api/components/pagination.md)

```tsx live
<Pagination>
  <Pagination.List>
    <Pagination.Link>&laquo;</Pagination.Link>
    <Pagination.Link active>1</Pagination.Link>
    <Pagination.Link>2</Pagination.Link>
    <Pagination.Link>3</Pagination.Link>
    <Pagination.Ellipsis />
    <Pagination.Link>10</Pagination.Link>
    <Pagination.Link>&raquo;</Pagination.Link>
  </Pagination.List>
</Pagination>
```

---

## Content

### Card

A Bulma-styled card with optional header, image, content, and footer. [View full documentation.](../../api/components/card.md)

```tsx live
<Card
  header="Card Header"
  image="https://images.unsplash.com/photo-1506744038136-46273834b3fb?auto=format&fit=crop&w=600&q=80"
  imageAlt="Beautiful forest"
  footer={[
    
      Save
    ,
    
      Cancel
    ,
  ]}
>
  Card content goes here.
</Card>
```

---

### Panel

A vertical panel block for lists, filters, or grouped actions. [View full documentation.](../../api/components/panel.md)

```tsx live
<Panel>
  <Panel.Heading>Revolutionary Figures</Panel.Heading>
  <Panel.InputBlock placeholder="Search" />
  <Panel.Tabs>
    All
    Patriots
    Loyalists
    Battles
    Documents
  </Panel.Tabs>
  <Panel.Block active>
    <Panel.Icon>
      
    </Panel.Icon>
    George Washington
  </Panel.Block>
  <Panel.Block>
    <Panel.Icon>
      
    </Panel.Icon>
    Alexander Hamilton
  </Panel.Block>
  <Panel.Block>
    <Panel.Icon>
      
    </Panel.Icon>
    Benedict Arnold
  </Panel.Block>
</Panel>
```

---

### Carousel

Image/content slider with navigation arrows and indicators. Supports auto-play, drag navigation, and customizable styles. [View full documentation.](../../api/components/carousel.md)

```tsx live
<Carousel indicatorStyle="lines" arrowHover>
  <CarouselItem>
    
      
      
        <Title subtitle textColor="white">
          Galaxy Horizon
        </Title>
      
    
  </CarouselItem>
  <CarouselItem>
    
      
      
        <Title subtitle textColor="white">
          Night Sky Vista
        </Title>
      
    
  </CarouselItem>
  <CarouselItem>
    
      
      
        <Title subtitle textColor="white">
          Starry Night
        </Title>
      
    
  </CarouselItem>
</Carousel>
```

---

### Collapse

Expandable/collapsible content panels with smooth animation. Works in controlled or uncontrolled mode. [View full documentation.](../../api/components/collapse.md)

```tsx live
<Collapse trigger={<Button>Click to expand</Button>}>
  <Box mt="3">
    This content is revealed when the collapse is opened.
    Click the button again to hide it.
  </Box>
</Collapse>
```

---

## Overlays

### Modal

A flexible, accessible modal dialog for dialogs, confirmations, or custom content. [View full documentation.](../../api/components/modal.md)

```tsx live
function example() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button color="success" onClick={() => setOpen(true)}>
        Show Modal
      </Button>
      <Modal
        active={open}
        onClose={() => setOpen(false)}
        modalCardTitle="Modal Card Title"
        modalCardFoot={
          <Buttons>
            <Button color="primary">Save</Button>
            <Button color="warning">Cancel</Button>
          </Buttons>
        }
      >
        Modal card body content goes here...
      </Modal>
    </>
  );
}
```

---

### Dialog

Confirmation and alert dialogs with customizable actions. Supports different types with matching icons. [View full documentation.](../../api/components/dialog.md)

```tsx live
function DialogExample() {
  const [showDialog, setShowDialog] = React.useState(false);
  return (
    
      <Button color="danger" onClick={() => setShowDialog(true)}>
        Delete Item
      </Button>
      <Dialog
        isOpen={showDialog}
        title="Delete Item?"
        message="This action cannot be undone."
        type="danger"
        confirmText="Delete"
        onConfirm={() => setShowDialog(false)}
        onCancel={() => setShowDialog(false)}
      />
    
  );
}
```

---

### Sidebar

Slide-out navigation panel from left or right. Supports overlay, custom width, and keyboard navigation. [View full documentation.](../../api/components/sidebar.md)

:::tip Live Preview Only
The `inline` prop and wrapper `` with positioning styles are only needed to display this component within the docs preview. **Do not copy them** — in your app, `Sidebar` renders via a portal automatically.
:::

```tsx live
function SidebarExample() {
  const [isOpen, setIsOpen] = React.useState(false);
  return (
    
      <Button color="primary" onClick={() => setIsOpen(true)}>
        Open Sidebar
      </Button>
      <Sidebar
        inline
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        style={{ position: 'absolute' }}
      >
        <Sidebar.Header>
          <Sidebar.Title>Navigation</Sidebar.Title>
          <Sidebar.Close onClick={() => setIsOpen(false)} />
        </Sidebar.Header>
        <Sidebar.Body>
          <Menu>
            <Menu.Label>Pages</Menu.Label>
            <Menu.List>
              <Menu.Item active>Home</Menu.Item>
              <Menu.Item>Products</Menu.Item>
              <Menu.Item>Services</Menu.Item>
              <Menu.Item>Contact</Menu.Item>
            </Menu.List>
          </Menu>
        </Sidebar.Body>
        <Sidebar.Footer>
          <Paragraph textSize="7" textColor="grey">
            © 2026 Company Name
          </Paragraph>
        </Sidebar.Footer>
      </Sidebar>
    
  );
}
```

---

### Loading

Full-page or container loading overlay with spinner. Supports cancel functionality and custom messages. [View full documentation.](../../api/components/loading.md)

:::tip Live Preview Only
The wrapper `` with positioning styles is only needed to display this component within the docs preview. **Do not copy it** — in your app, `Loading` renders as a full-page overlay automatically.
:::

```tsx live
function LoadingExample() {
  const [isLoading, setIsLoading] = React.useState(false);
  return (
    
      <Button onClick={() => setIsLoading(!isLoading)}>Toggle Loading</Button>
      <Loading
        active={isLoading}
        canCancel
        onCancel={() => setIsLoading(false)}
      >
        Loading data...
      </Loading>
    
  );
}
```

---

## Menus

### Menu

A vertical navigation menu for sidebars, dashboards, or grouped navigation. [View full documentation.](../../api/components/menu.md)

```tsx live
<Menu style={{ maxWidth: 300 }}>
  <Menu.Label>General</Menu.Label>
  <Menu.List>
    <Menu.Item>Dashboard</Menu.Item>
    <Menu.Item>Customers</Menu.Item>
  </Menu.List>
  <Menu.Label>Administration</Menu.Label>
  <Menu.List>
    <Menu.Item>Team Settings</Menu.Item>
    <Menu.Item active>Manage Your Team</Menu.Item>
  </Menu.List>
</Menu>
```

---

### Dropdown

A versatile dropdown menu for navigation, actions, or pop-up lists. [View full documentation.](../../api/components/dropdown.md)

```tsx live
<Dropdown label="Dropdown Menu">
  <Dropdown.Item>First Item</Dropdown.Item>
  <Dropdown.Item>Second Item</Dropdown.Item>
  <Dropdown.Divider />
  <Dropdown.Item>Third Item</Dropdown.Item>
  <Dropdown.Item>Fourth Item</Dropdown.Item>
  <Dropdown.Item>Fifth Item</Dropdown.Item>
</Dropdown>
```

---

## Feedback

### Message

A Bulma-styled message box for feedback, alerts, or notifications. [View full documentation.](../../api/components/message.md)

```tsx live
<Message color="primary" title="Primary">
  This is a primary message.
</Message>
```

---

### Toast

Brief notification messages with optional action and cancel buttons. Supports multiple positions, colors, an explicit close button, and a programmatic API. [View full documentation.](../../api/components/toast.md)

:::note
Toast and Dialog provide programmatic APIs for showing notifications from anywhere in your app. Add the container component once at your app root, then call `toast.success()` or `dialog.confirm()` from any component.
:::

:::tip Live Preview Only
The `inline` prop is only needed to display this component within the docs preview. **Do not copy it** — in your app, `Toast` renders via a portal automatically.
:::

```tsx live
function ToastExample() {
  const [showToast, setShowToast] = React.useState(false);
  return (
    
      <Button color="info" onClick={() => setShowToast(true)}>
        Show Toast
      </Button>
      {showToast && (
        <Toast
          inline
          message="Item deleted"
          actionText="Undo"
          actionType="info"
          onAction={() => console.log('Undo clicked')}
          onClose={() => setShowToast(false)}
        />
      )}
    
  );
}
```

---

### Tooltip

Hover tooltips for displaying helpful information. Supports multiple positions and colors. [View full documentation.](../../api/components/tooltip.md)

```tsx live

  <Tooltip label="This is helpful information" position="top">
    <Button>Hover me (top)</Button>
  </Tooltip>
  <Tooltip label="Positioned on the right" position="right" color="info">
    <Button color="info">Hover me (right)</Button>
  </Tooltip>

```

---

:::tip
All components support Bulma helper props for color, spacing, and accessibility. See the full documentation for each component for more advanced usage and customization.
:::

:::info
Components are higher-level building blocks. For lower-level primitives, see the Elements section.
:::

---

## Elements


The **Elements** section provides foundational UI building blocks for your Bulma React applications. These components are designed to be simple, composable, and highly customizable, covering everything from typography and layout containers to interactive controls and feedback elements. Each element supports Bulma's utility props for color, spacing, and accessibility, making it easy to create beautiful, consistent interfaces.

:::info
Elements are the core primitives of the Bestax Bulma library. They are intended to be used directly or as building blocks for more complex components.
:::

---

## Layout

### Block

A simple container with vertical margin for grouping or spacing content sections. [View full documentation.](../../../api/elements/block.md)

```tsx live
<Block>Default Block</Block>
```

---

### Box

A bordered, padded container with optional shadow, ideal for grouping or highlighting content. [View full documentation.](../../../api/elements/box.md)

```tsx live
<Box>Default Box</Box>
```

---

### Divider

A horizontal rule (``) for visually separating content sections. [View full documentation.](../../../api/elements/divider.md)

```tsx live

  <Block>Content above</Block>
  <Divider my="4" />
  <Block>Content below</Block>

```

---

## Typography

### Title

A Bulma-styled title (heading), supporting sizes, spacing, and rendering as any heading or paragraph element. [View full documentation.](../../../api/elements/title.md)

```tsx live
<Title>Default Title</Title>
```

---

### SubTitle

A Bulma-styled subtitle (secondary heading), supporting sizes and rendering as any heading or paragraph element. [View full documentation.](../../../api/elements/subtitle.md)

```tsx live
<SubTitle>Default SubTitle</SubTitle>
```

---

### Content

Applies Bulma's typographic styles to children, perfect for rendering rich or markdown-like HTML content. [View full documentation.](../../../api/elements/content.md)

```tsx live
<Content>
  This is a paragraph inside Content.
</Content>
```

---

## Text

### Paragraph

A paragraph (``) wrapper with typography and spacing helpers. [View full documentation.](../../../api/elements/paragraph.md)

```tsx live
<Paragraph textColor="info" textAlign="centered">
  A centered, info-colored paragraph.
</Paragraph>
```

---

### Span

An inline (``) wrapper for styling text without semantic meaning. [View full documentation.](../../../api/elements/span.md)

```tsx live
<Paragraph>
  This text has a colored span inside it.
</Paragraph>
```

---

### Strong

A strong (``) wrapper for semantically important bold text. [View full documentation.](../../../api/elements/strong.md)

```tsx live
<Paragraph>
  This text has important information highlighted.
</Paragraph>
```

---

### Emphasis

An emphasis (``) wrapper for semantically emphasized italic text. [View full documentation.](../../../api/elements/emphasis.md)

```tsx live
<Paragraph>
  You should <Emphasis>really</Emphasis> pay attention to this.
</Paragraph>
```

---

### Code

An inline code (`<code>`) wrapper for short code snippets. [View full documentation.](../../../api/elements/code.md)

```tsx live
<Paragraph>
  Run <Code>pnpm install</Code> to install dependencies.
</Paragraph>
```

---

### Pre

A preformatted text (`<pre>`) wrapper for code blocks. [View full documentation.](../../../api/elements/pre.md)

```tsx live
<Pre bgColor="dark" textColor="white" p="4">
  {`function hello() {
  console.log("Hello!");
}`}
</Pre>
```

---

### Link

A styled anchor (``) wrapper for navigation links with Bulma helper support. [View full documentation.](../../../api/elements/link.md)

```tsx live
<Link href="#" textColor="primary">
  Primary Link
</Link>
```

---

## Buttons

### Button

A flexible, highly customizable button supporting all Bulma color, size, and state modifiers. [View full documentation.](../../../api/elements/button.md)

```tsx live
<Button>Default Button</Button>
```

---

### Buttons

A group container for multiple `Button` elements, supporting spacing, alignment, and add-ons. [View full documentation.](../../../api/elements/buttons.md)

```tsx live
<Buttons>
  <Button color="primary">Save</Button>
  <Button color="info">Edit</Button>
  <Button color="danger">Delete</Button>
</Buttons>
```

---

### LinkButton

A `<button>` that visually looks like text or a link. Supports `text` and `ghost` variants with optional color overrides. [View full documentation.](../../../api/elements/linkbutton.md)

:::warning Accessibility
Using `` or `` without an `href` are common anti-patterns flagged by [`eslint-plugin-jsx-a11y`](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y):

- **`no-static-element-interactions`** — catches clickable ``s and other non-interactive elements
- **`anchor-is-valid`** — catches `` tags with `onClick` but no valid `href`

These elements are invisible or misleading to screen readers because they lack semantic role, keyboard focus, and key-event handling. `LinkButton` solves this by rendering a native `<button>` with full keyboard and screen-reader support — while still looking like plain text or a link.
:::

```tsx live
<Buttons>
  <LinkButton>Text Variant</LinkButton>
  <LinkButton variant="ghost">Ghost Variant</LinkButton>
  <LinkButton color="primary">Primary Text</LinkButton>
  <LinkButton variant="ghost" color="danger">
    Danger Ghost
  </LinkButton>
</Buttons>
```

---

## Media

### Icon

A wrapper for displaying icons from various libraries, handling Bulma sizing, color, and accessibility. [View full documentation.](../../../api/elements/icon.md)

```tsx live
<Icon name="star" ariaLabel="Star icon" />
```

---

### IconText

A horizontal arrangement of one or more icons and optional text, ideal for icon-and-label patterns. [View full documentation.](../../../api/elements/icontext.md)

```tsx live
<IconText iconProps={{ name: 'fas fa-star', ariaLabel: 'Star icon' }}>
  Star
</IconText>
```

---

### Image

A Bulma-styled container for images, iframes, or custom content, supporting sizes, aspect ratios, and more. [View full documentation.](../../../api/elements/image.md)

```tsx live
<Image src="/img/react-logo.png" alt="Sample image" size="128x128" />
```

---

### Figure

A figure (`<figure>`) wrapper for grouping content with an optional caption. [View full documentation.](../../../api/elements/figure.md)

```tsx live
<Figure bgColor="light" textColor="dark" p="4">
  <Image src="/img/logo.png" alt="Example" size="128x128" />
  <Figure.Caption mt="2">Figure caption</Figure.Caption>
</Figure>
```

---

## Lists

### UnorderedList

An unordered list (``) wrapper with Bulma helper support. [View full documentation.](../../../api/elements/unorderedlist.md)

```tsx live
<Content>
  <UnorderedList>
    <ListItem>First item</ListItem>
    <ListItem>Second item</ListItem>
    <ListItem>Third item</ListItem>
  </UnorderedList>
</Content>
```

---

### OrderedList

An ordered list (``) wrapper supporting numbering types and Bulma helpers. [View full documentation.](../../../api/elements/orderedlist.md)

```tsx live
<Content>
  <OrderedList type="A">
    <ListItem>First item</ListItem>
    <ListItem>Second item</ListItem>
    <ListItem>Third item</ListItem>
  </OrderedList>
</Content>
```

---

### ListItem

A list item (``) wrapper for use inside UnorderedList or OrderedList. [View full documentation.](../../../api/elements/listitem.md)

```tsx live
<Content>
  <UnorderedList>
    <ListItem textColor="primary">Primary item</ListItem>
    <ListItem textColor="success">Success item</ListItem>
    <ListItem textColor="danger">Danger item</ListItem>
  </UnorderedList>
</Content>
```

---

## Data

### Table

A highly composable, Bulma-styled table system with full support for Bulma's table features. Compose it with the `Thead`, `Tbody`, `Tfoot`, `Tr`, `Th`, and `Td` sub-components, all covered on the Table page. [View full documentation.](../../../api/elements/table.md)

```tsx live

  
    
      Name
      Value
    
  
  
    
      Example
      42
    
  

```

---

### Tag

A Bulma-styled label or badge, supporting color, size, rounded, hoverable, and delete variants. [View full documentation.](../../../api/elements/tag.md)

```tsx live
<Tag>Default Tag</Tag>
```

---

### Tags

A container for grouping multiple `Tag` components, supporting add-ons and multiline layouts. [View full documentation.](../../../api/elements/tags.md)

```tsx live
<Tags>
  <Tag color="primary">Primary</Tag>
  <Tag color="info">Info</Tag>
  <Tag color="success">Success</Tag>
</Tags>
```

---

## Feedback

### Notification

A Bulma-styled alert/message area for feedback, warnings, or information, with color and close button support. [View full documentation.](../../../api/elements/notification.md)

```tsx live
<Notification>This is a default notification.</Notification>
```

---

### Progress

A Bulma-styled progress bar for visualizing task completion, loading states, or feedback. [View full documentation.](../../../api/elements/progress.md)

```tsx live
<Progress value={50} max={100} />
```

---

### Skeleton

A skeleton loader for indicating loading content, with block or lines variants. [View full documentation.](../../../api/elements/skeleton.md)

```tsx live
<Skeleton />
```

---

## Utility

### Delete

A Bulma-styled close/delete button for dismissing modals, notifications, tags, and more. [View full documentation.](../../../api/elements/delete.md)

```tsx live
<Delete />
```

---

:::tip
For advanced customization, all elements support Bulma helper props for color, spacing, and accessibility. See the full documentation for each component for more details and advanced usage.
:::

:::caution
Elements are low-level building blocks. For more complex UI patterns, consider using the higher-level components and layout primitives provided elsewhere in the library.
:::

---

## Form Components Overview

# Form Components

This page provides a summary of all Bulma-styled form components in Bestax, with a brief description, usage example, and links to full documentation for each. Use these components to build accessible, flexible, and visually consistent forms.

---

## Text Inputs

### Input

A Bulma-styled text input supporting color, size, rounded, static/read-only, and loading states. Pass `label`, `iconLeftName`/`iconRightName`, and `message`/`messageColor` to auto-wrap with a `Field` and `Control` — no extra boilerplate.

```tsx live
<Input
  label="Email"
  placeholder="you@example.com"
  iconLeftName="envelope"
  message="We'll never share your email"
  messageColor="info"
/>
```

[View full documentation.](../../api/form/input)

:::tip Escape hatch
For complex layouts (grouped fields, addons, horizontal forms), use `InputBase` with an explicit `Field` + `Control` wrapper.
:::

---

### TextArea

A Bulma-styled multi-line text input. Supports color, size, rounded, static/read-only, and fixed size. Also accepts `label`, `message`, and `messageColor` for one-stop field usage.

```tsx live
<TextArea
  label="Comments"
  placeholder="Tell us your thoughts..."
  rows={3}
  message="Max 500 characters"
  messageColor="info"
/>
```

[View full documentation.](../../api/form/textarea)

:::tip Escape hatch
For complex layouts, use `TextAreaBase` with an explicit `Field` + `Control` wrapper.
:::

---

### Autocomplete

Input with dropdown suggestions. Filters options based on user input with keyboard navigation.

```tsx live
function AutocompleteExample() {
  const [selected, setSelected] = React.useState(null);
  const fruits = [
    'Apple',
    'Banana',
    'Cherry',
    'Date',
    'Elderberry',
    'Fig',
    'Grape',
  ];
  return (
    
      <Autocomplete
        data={fruits}
        placeholder="Search fruit..."
        onSelect={setSelected}
        openOnFocus
        clearable
      />
      {selected && Selected: {selected}}
    
  );
}
```

[View full documentation.](../../api/form/autocomplete)

---

## Selection

### Checkbox

A Bulma-styled checkbox input for boolean choices. Pass the label as children; supports custom JSX and links.

```tsx live
<Checkbox> Stay Signed In </Checkbox>
```

[View full documentation.](../../api/form/checkbox)

---

### Checkboxes

Wraps multiple `Checkbox` components in a vertical group for lists of boolean options (e.g., preferences, to-do lists).

```tsx live
<Checkboxes>
  <Checkbox> Option 1 </Checkbox>
  <Checkbox> Option 2 </Checkbox>
</Checkboxes>
```

[View full documentation.](../../api/form/checkboxes)

---

### Radio

A Bulma-styled radio button for mutually exclusive choices. Use the same `name` prop for grouping.

```tsx live
<Radio name="group"> Option A </Radio>
```

[View full documentation.](../../api/form/radio)

---

### Radios

Groups multiple `Radio` components vertically for single-choice lists (e.g., RSVP, selection lists).

```tsx live
<Radios>
  <Radio name="event"> Attend </Radio>
  <Radio name="event"> Decline </Radio>
</Radios>
```

[View full documentation.](../../api/form/radios)

---

### Select

A Bulma-styled dropdown for single or multiple selections. Supports color, size, rounded, loading, and multiselect. Accepts `label`, `iconLeftName`, and `message`/`messageColor` to auto-wrap with `Field` and `Control`.

```tsx live
<Select label="Country" iconLeftName="globe">
  <option>United States</option>
  <option>Canada</option>
  <option>United Kingdom</option>
</Select>
```

[View full documentation.](../../api/form/select)

:::tip Escape hatch
For complex layouts, use `SelectBase` with an explicit `Field` + `Control` wrapper.
:::

---

### Switch

Toggle switch for on/off states. A styled checkbox that appears as a toggle, commonly used for settings.

```tsx live
function SwitchExample() {
  const [enabled, setEnabled] = React.useState(false);
  return (
    
      <Switch
        checked={enabled}
        onChange={e => setEnabled(e.target.checked)}
        color="success"
        isRounded
      >
        Enable notifications
      </Switch>
      
        Status: {enabled ? 'Enabled' : 'Disabled'}
      
    
  );
}
```

[View full documentation.](../../api/form/switch)

---

## Number / Range

### Numberinput

Number input with increment/decrement buttons. Provides +/- buttons for easy value adjustment.

```tsx live
function NumberinputExample() {
  const [quantity, setQuantity] = React.useState(1);
  return (
    
      <Numberinput
        value={quantity}
        onChange={setQuantity}
        min={1}
        max={10}
        color="primary"
      />
      Quantity: {quantity}
    
  );
}
```

[View full documentation.](../../api/form/numberinput)

---

### Slider

Range slider for selecting values. Supports different sizes, colors, and optional value display.

```tsx live
function SliderExample() {
  const [value, setValue] = React.useState(50);
  return (
    
      <Slider
        value={value}
        onChange={setValue}
        min={0}
        max={100}
        showOutput
        color="primary"
        isRounded
      />
      Value: {value}
    
  );
}
```

[View full documentation.](../../api/form/slider)

---

### Rate

Star/icon-based rating component. Supports custom icons, sizes, and text labels.

```tsx live
function RateExample() {
  const [rating, setRating] = React.useState(3);
  return (
    
      <Rate
        value={rating}
        onChange={setRating}
        showScore
        showText
        texts={['Poor', 'Fair', 'Average', 'Good', 'Excellent']}
      />
    
  );
}
```

[View full documentation.](../../api/form/rate)

---

## Date & Time

### DateInput

A date input that opens a popover calendar, with segmented keyboard entry directly in the field. Built on native `Date` and `Intl` only — supports min/max bounds, disabled-date predicates, custom formats, locales, an inline mode, and a native fallback on touch devices.

```tsx live
function DateInputExample() {
  const [date, setDate] = React.useState(null);
  return (
    
      <DateInput
        label="Date"
        placeholder="YYYY-MM-DD"
        value={date}
        onChange={setDate}
      />
      Selected: {date ? date.toDateString() : '—'}
    
  );
}
```

[View full documentation.](../../api/form/datetime/dateinput)

---

### TimeInput

A time-of-day input that opens a popover wheel spinner, with segmented keyboard entry directly in the field. Supports 12/24-hour formats, optional seconds, custom increments, min/max bounds, and a native fallback on touch devices.

```tsx live
function TimeInputExample() {
  const [time, setTime] = React.useState(null);
  return (
    
      <TimeInput
        label="Time"
        placeholder="HH:MM AM"
        hourFormat="12"
        value={time}
        onChange={setTime}
      />
      Selected: {time ? time.toLocaleTimeString() : '—'}
    
  );
}
```

[View full documentation.](../../api/form/datetime/timeinput)

---

### DateTimeInput

Combines the calendar and time wheels in a single popover with an iOS-style footer — the selected time, a Reset button, and a ✓ confirm button. Click the time to float the wheel spinner over the calendar. Supports the full prop surface of both `DateInput` and `TimeInput`.

```tsx live
<DateTimeInput label="Appointment" placeholder="YYYY-MM-DD HH:MM" />
```

[View full documentation.](../../api/form/datetime/datetimeinput)

---

## Tags

### Taginput

Tag/chip input field for managing multiple tags. Supports autocomplete suggestions and custom styling.

```tsx live
function TaginputExample() {
  const [tags, setTags] = React.useState(['React', 'TypeScript']);
  const suggestions = [
    'React',
    'Vue',
    'Angular',
    'Svelte',
    'TypeScript',
    'JavaScript',
  ];
  return (
    
      <Taginput
        value={tags}
        onChange={setTags}
        data={suggestions}
        placeholder="Add frameworks..."
        tagColor="primary"
      />
      Tags: {tags.join(', ')}
    
  );
}
```

[View full documentation.](../../api/form/taginput)

---

## File Upload

### File

A Bulma-styled file input with support for color, size, boxed/fullwidth/align styles, icons, and filename display.

```tsx live
<File label="Choose a file..." />
```

[View full documentation.](../../api/form/file)

---

## Layout

### Field

A Bulma-styled form field container for labels, grouped controls, and horizontal layouts. Compose labeled, grouped, or horizontal form layouts.

```tsx live
<Field label="Email">
  <Input placeholder="you@example.com" />
</Field>
```

[View full documentation.](../../api/form/field)

:::tip
Use `Field` to group and label form controls for accessibility and layout.
:::

---

### Control

A Bulma-styled wrapper for form controls, providing consistent spacing, icon placement, and loading indicators.

```tsx live
<Control>
  <Input placeholder="Username" />
</Control>
```

[View full documentation.](../../api/form/control)

:::tip
Wrap inputs, selects, or textareas in `Control` for proper Bulma styling and icon support.
:::

---

For more details and advanced usage, see the full documentation for each component linked above.

---

## Grid Components Overview

# Grid Components

This page summarizes the Bulma-styled grid system in Bestax, with a brief description, usage example, and links to full documentation for each. Use these components for advanced, responsive, and modern CSS grid layouts.

---

## Grid

Provides Bulma's advanced CSS Grid layout for complex, modern layouts. Supports responsive and fixed grid modes, gap and min column controls, fixed column counts per breakpoint, and full color/background/utility helpers. Use with `Cell` for granular grid placement.

:::info
Use `Grid` for advanced layouts where you need more control than Columns can provide. It supports both auto-fit and fixed column counts.
:::

```tsx live
<Grid>
  {[...Array(4)].map((_, i) => (
    <Cell key={i}>
      <Notification color="primary">Cell {i + 1}</Notification>
    </Cell>
  ))}
</Grid>
```

**Fixed Columns**

Set the `isFixed` and `fixedCols` props to create a grid with a fixed number of columns.

:::tip
Fixed grids are great for dashboards or galleries where you want a consistent number of columns at each breakpoint.
:::

```tsx live
<Grid isFixed fixedCols={3}>
  {[...Array(6)].map((_, i) => (
    <Cell key={i}>
      <Notification color="info">Fixed {i + 1}</Notification>
    </Cell>
  ))}
</Grid>
```

**Custom Gaps**

Control the gap between grid cells using the `gap`, `columnGap`, or `rowGap` props.

:::caution
Setting very large gaps can cause layout issues on small screens. Test your grid at all breakpoints.
:::

```tsx live
<Grid gap={6}>
  <Cell>
    <Notification color="success">Gap 1</Notification>
  </Cell>
  <Cell>
    <Notification color="warning">Gap 2</Notification>
  </Cell>
</Grid>
```

[View full documentation.](../../api/grid)

---

## Cell

A single Bulma grid cell for use inside the `Grid` component. Supports all Bulma grid CSS classes for manual placement and spanning, color/background helpers, and all utility/HTML props.

**Manual Placement**

Use the `colSpan` and `rowSpan` props to control how many columns or rows a cell should span.

:::tip
Spanning cells is useful for headers, footers, or feature cards that need to take up more space.
:::

```tsx live
<Grid isFixed fixedCols={3}>
  <Cell colSpan={2}>
    <Notification color="primary">Span 2 columns</Notification>
  </Cell>
  <Cell>
    <Notification color="info">Normal</Notification>
  </Cell>
  <Cell>
    <Notification color="success">Normal</Notification>
  </Cell>
</Grid>
```

[View full documentation.](../../api/grid/cell)

---

For more details and advanced usage, see the full documentation for each component linked above.

---

## Helper Utilities Overview

# Helper Utilities

This page summarizes the helper utilities in Bestax, with a brief description, usage example, and links to full documentation for each. Use these helpers to simplify class name management and apply Bulma utility classes in a type-safe, composable way.

---

## Helper props at a glance

Most components accept these shared helper props (they map to Bulma utility classes via [`useBulmaClasses`](../../api/helpers/usebulmaclasses); a few thin wrappers like `Skeleton` opt out). Prefer them over inline `style` — they are type-checked, theme-aware, and responsive.

| Group          | Representative props                                                          | Example                   | Renders                     |
| -------------- | ----------------------------------------------------------------------------- | ------------------------- | --------------------------- |
| **Spacing**    | `m` `mt` `mb` `ml` `mr` `mx` `my` `p` `pt` `pb` `px` `py` (`0`–`6` \| `auto`) | `mt="4"`                  | `mt-4`                      |
| **Color**      | `textColor` `bgColor` `colorShade`                                            | `textColor="primary"`     | `has-text-primary`          |
| **Typography** | `textSize` `textAlign` `textWeight` `textTransform` `fontFamily`              | `textAlign="centered"`    | `has-text-centered`         |
| **Display**    | `display` `visibility`                                                        | `display="flex"`          | `is-flex`                   |
| **Flexbox**    | `flexDirection` `justifyContent` `alignItems` `flexGrow` `flexShrink`         | `justifyContent="center"` | `is-justify-content-center` |
| **Other**      | `float` `radius` `shadow` `overflow` `clearfix`                               | `float="right"`           | `is-pulled-right`           |

## Inline styles → helper props

Reach for a helper prop before an inline `style`. Reserve `style` / CSS variables only for values the design system doesn't tokenize (e.g. a one-off brand hex).

| Instead of…                       | Use                              | Renders                    |
| --------------------------------- | -------------------------------- | -------------------------- |
| `style={{ marginTop: '1rem' }}`   | `mt="4"`                         | `mt-4`                     |
| `style={{ padding: '0.5rem' }}`   | `p="2"`                          | `p-2`                      |
| `style={{ textAlign: 'center' }}` | `textAlign="centered"`           | `has-text-centered`        |
| `style={{ color: '…' }}`          | `textColor="…"` (+ `colorShade`) | `has-text-…`               |
| `style={{ background: '…' }}`     | `bgColor="…"`                    | `has-background-…`         |
| `style={{ fontWeight: 600 }}`     | `textWeight="semibold"`          | `has-text-weight-semibold` |
| `style={{ display: 'flex' }}`     | `display="flex"`                 | `is-flex`                  |

Spacing scale: `0` = 0, `1` = 0.25rem, `2` = 0.5rem, `3` = 0.75rem, `4` = 1rem, `5` = 1.5rem, `6` = 3rem, `auto` = auto. See [margin & padding](../helpers/margin-and-padding) for every side.

---

## useBulmaClasses

A custom React hook that generates Bulma helper class strings from a set of props. Makes it easy to apply color, spacing, alignment, typography, flexbox, and other Bulma utility classes to your components. Returns both the class string and the remaining props for spreading onto elements.

### Color

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

```tsx live
<Button color="primary">Primary Button</Button>
```

### Color Palette

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

```tsx live
<Box bgColor="info" colorShade="30">
  Info 30
</Box>
```

### Spacing

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

```tsx live
<Box m="4" px="2" py="5">
  Box with margin and padding
</Box>
```

### Typography

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

```tsx live
<Box
  textSize="3"
  textAlign="centered"
  textTransform="uppercase"
  textWeight="bold"
  fontFamily="monospace"
>
  Typography Example
</Box>
```

### Visibility

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

```tsx live
<Button visibility="hidden" viewport="mobile">
  Hidden on Mobile
</Button>
```

### Flexbox

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

```tsx live
<Box
  display="flex"
  flexDirection="row"
  justifyContent="center"
  alignItems="center"
>
  <Button>Left</Button>
  <Button>Center</Button>
  <Button>Right</Button>
</Box>
```

### Other

Additional Bulma helpers are supported via these props:

#### is-clearfix

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

Use the `clearfix` prop.

```tsx live
<Box clearfix>
  <Button float="left">Left</Button>
  <Button float="right">Right</Button>
</Box>
```

#### is-pulled-left / is-pulled-right

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

:::note

Notice in the example that the float is reversing the rendered order of the elements

:::

Use the `float` prop.

```tsx live
<>
  <Button float="Right">Pulled Right</Button>
  <Button float="left">Pulled Left</Button>
</>
```

#### is-overlay

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

Use the `overlay` prop.

```tsx
<Box overlay>
  Overlay Content
  
</Box>
```

#### is-clipped

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

Use the `overflow` prop.

```tsx live
<Message overflow="clipped" style={{ width: 200, height: '3.25rem' }}>
  This is a very long line of text that will be clipped and not overflow the
  box.
</Message>
```

#### is-radiusless

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

Use the `radius` prop.

```tsx live
<Button radius="radiusless">Radiusless Button</Button>
```

#### is-shadowless

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

Use the `shadow` prop.

```tsx live
<Box shadow="shadowless">No Shadow</Box>
```

#### is-unselectable

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

Use the `interaction` prop.

:::tip

Try to select me, bet you can't!

:::

```tsx live
<Box interaction="unselectable">Unselectable Text</Box>
```

#### is-clickable

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

Use the `interaction` prop.

```tsx live
<Box interaction="clickable">Clickable Box</Box>
```

#### is-relative

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

Use the `relative` prop.

```tsx live
<Box relative p="4" style={{ height: '100px', border: '1px dashed #ccc' }}>
  <Tag style={{ position: 'absolute', top: '8px', right: '8px' }}>Badge</Tag>
  Relative container
</Box>
```

#### is-cursor-help

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

Use the `cursor` prop.

```tsx live
<Box cursor="help">Hover for help cursor</Box>
```

#### is-full-height

:::info
More examples and full property coverage are available in [usebulmaclasses.md](../../api/helpers/usebulmaclasses).
:::

Use the `fullHeight` prop.

```tsx live
<Columns>
  <Column>
    <Notification color="primary" fullHeight>
      Short content
    </Notification>
  </Column>
  <Column>
    <Notification color="info" fullHeight>
      Taller content that takes more space to demonstrate equal height
    </Notification>
  </Column>
</Columns>
```

[View full documentation.](../../api/helpers/usebulmaclasses)

---

## classNames

A utility function for conditionally joining class names together. Accepts any mix of strings, numbers, arrays, or objects, and returns a space-separated string of unique class names. Useful for dynamically constructing `className` values in React and other frameworks.

```tsx
classNames('column', 'is-half', {
  'has-text-primary': true,
  'is-hidden': false,
});
// => 'column is-half has-text-primary'
```

[View full documentation.](../../api/helpers/classnames)

---

## Theme

A component that injects Bulma CSS variables for local or global theming. Wrap any subtree in `<Theme>` to override design tokens like colors, typography, and spacing without writing custom CSS.

[View full documentation.](../../api/helpers/theme)

---

## ConfigProvider

A context provider for global settings like class prefix and icon library. Wrap your app in `<ConfigProvider>` to configure all bestax-bulma components at once — e.g. set `iconLibrary="fa"` once at the root so `<Icon name="check" />` needs no per-icon `library` prop.

[View full documentation.](../../api/helpers/config) · [Configuration guide](../features/configuration)

---

For more details and advanced usage, see the full documentation for each helper linked above.

---

## Library Overview


**bestax-bulma** wraps every Bulma CSS class in a typed React component, giving you full IntelliSense, prop-level validation, and zero class-string wiring. The library mirrors Bulma's own layered design so that mapping between the CSS docs and the React API is always one-to-one.

```tsx live
<Box>
  <Columns isVCentered>
    <Column isNarrow>
      <Icon name="cube" size="large" textColor="primary" ariaLabel="library" />
    </Column>
    <Column>
      <Title size="4" mb="1">
        80 typed components
      </Title>
      <SubTitle size="6" textColor="grey">
        Elements, Components, Form, Layout — all in one package.
      </SubTitle>
    </Column>
    <Column isNarrow>
      <Tags>
        <Tag color="primary">React</Tag>
        <Tag color="info">Bulma v1</Tag>
        <Tag color="success">TypeScript</Tag>
      </Tags>
    </Column>
  </Columns>
</Box>
```

---

## Architecture

Bulma organises its styles into a clear hierarchy, and bestax-bulma mirrors it exactly:

```tsx live
<Grid isFixed fixedCols={3} gap={4}>
  <Cell>
    <Notification color="primary" textColor="black" fullHeight>
      <Title size="5" textColor="black">
        Elements
      </Title>
      <Tag color="dark" isRounded>
        30
      </Tag>
      <Paragraph mt="2" textColor="black">
        Foundational atoms — buttons, tags, icons, typography
      </Paragraph>
      
        See more &rarr;
      
    </Notification>
  </Cell>
  <Cell>
    <Notification color="link" textColor="black" fullHeight>
      <Title size="5" textColor="black">
        Components
      </Title>
      <Tag color="dark" isRounded>
        19
      </Tag>
      <Paragraph mt="2" textColor="black">
        Composed patterns — modals, navbars, cards, tabs
      </Paragraph>
      
        See more &rarr;
      
    </Notification>
  </Cell>
  <Cell>
    <Notification color="success" textColor="black" fullHeight>
      <Title size="5" textColor="black">
        Form
      </Title>
      <Tag color="dark" isRounded>
        16
      </Tag>
      <Paragraph mt="2" textColor="black">
        Input controls — text fields, selects, checkboxes
      </Paragraph>
      
        See more &rarr;
      
    </Notification>
  </Cell>
  <Cell>
    <Notification color="info" textColor="black" fullHeight>
      <Title size="5" textColor="black">
        Columns
      </Title>
      <Tag color="dark" isRounded>
        2
      </Tag>
      <Paragraph mt="2" textColor="black">
        Classic 12-column flexbox grid
      </Paragraph>
      
        See more &rarr;
      
    </Notification>
  </Cell>
  <Cell>
    <Notification color="warning" textColor="black" fullHeight>
      <Title size="5" textColor="black">
        Grid
      </Title>
      <Tag color="dark" isRounded>
        2
      </Tag>
      <Paragraph mt="2" textColor="black">
        Bulma v1 CSS-grid layout
      </Paragraph>
      
        See more &rarr;
      
    </Notification>
  </Cell>
  <Cell>
    <Notification color="danger" textColor="black" fullHeight>
      <Title size="5" textColor="black">
        Layout
      </Title>
      <Tag color="dark" isRounded>
        6
      </Tag>
      <Paragraph mt="2" textColor="black">
        Page-level containers — hero, footer, section
      </Paragraph>
      
        See more &rarr;
      
    </Notification>
  </Cell>
</Grid>
```

Every Bulma class has a corresponding React component in the matching tier, so the mental model you already know from Bulma transfers directly.

---

## Elements (30)

Foundational building blocks: typography, buttons, media, lists, data display, and feedback.

[Block](/docs/api/elements/block), [Box](/docs/api/elements/box), [Button](/docs/api/elements/button), [Buttons](/docs/api/elements/buttons), [Code](/docs/api/elements/code), [Content](/docs/api/elements/content), [Delete](/docs/api/elements/delete), [Divider](/docs/api/elements/divider), [Emphasis](/docs/api/elements/emphasis), [Figure](/docs/api/elements/figure), [Icon](/docs/api/elements/icon), [IconText](/docs/api/elements/icontext), [Image](/docs/api/elements/image), [Link](/docs/api/elements/link), [LinkButton](/docs/api/elements/linkbutton), [ListItem](/docs/api/elements/listitem), [Notification](/docs/api/elements/notification), [OrderedList](/docs/api/elements/orderedlist), [Paragraph](/docs/api/elements/paragraph), [Pre](/docs/api/elements/pre), [Progress](/docs/api/elements/progress), [Skeleton](/docs/api/elements/skeleton), [Span](/docs/api/elements/span), [Strong](/docs/api/elements/strong), [SubTitle](/docs/api/elements/subtitle), [Table](/docs/api/elements/table), [Tag](/docs/api/elements/tag), [Tags](/docs/api/elements/tags), [Title](/docs/api/elements/title), [UnorderedList](/docs/api/elements/unorderedlist)

```tsx live

  <Buttons>
    <Button color="primary">Primary</Button>
    <Button color="info" isOutlined>
      Info
    </Button>
    <Button color="success" isLight>
      Success
    </Button>
  </Buttons>
  <Progress value={65} max={100} color="primary" />
  <Tags mt="3">
    <Tag color="info">React</Tag>
    <Tag color="primary">Bulma</Tag>
    <Tag color="success">TypeScript</Tag>
    <Tag color="warning">Accessible</Tag>
  </Tags>

```

[Browse all Elements &rarr;](/docs/guides/library/elements)

---

## Components (18)

Higher-level composed UI patterns: navigation, overlays, feedback, and interactive controls.

[Breadcrumb](/docs/api/components/breadcrumb), [Card](/docs/api/components/card), [Carousel](/docs/api/components/carousel), [Collapse](/docs/api/components/collapse), [Dialog](/docs/api/components/dialog), [Dropdown](/docs/api/components/dropdown), [Loading](/docs/api/components/loading), [Menu](/docs/api/components/menu), [Message](/docs/api/components/message), [Modal](/docs/api/components/modal), [Navbar](/docs/api/components/navbar), [Pagination](/docs/api/components/pagination), [Panel](/docs/api/components/panel), [Sidebar](/docs/api/components/sidebar), [Steps](/docs/api/components/steps), [Tabs](/docs/api/components/tabs), [Toast](/docs/api/components/toast), [Tooltip](/docs/api/components/tooltip)

```tsx live
<Columns>
  <Column>
    <Card>
      <Card.Content>
        <Title size="5">Dashboard</Title>
        <SubTitle size="6" textColor="grey">
          Analytics overview
        </SubTitle>
        <Progress value={72} max={100} color="info" />
      </Card.Content>
    </Card>
  </Column>
  <Column>
    <Card>
      <Card.Content>
        <Title size="5">Users</Title>
        <SubTitle size="6" textColor="grey">
          Manage accounts
        </SubTitle>
        <Progress value={45} max={100} color="success" />
      </Card.Content>
    </Card>
  </Column>
</Columns>
```

[Browse all Components &rarr;](/docs/guides/library/components)

---

## Form (16)

Input controls for building accessible, flexible forms.

[Autocomplete](/docs/api/form/autocomplete), [Checkbox](/docs/api/form/checkbox), [Checkboxes](/docs/api/form/checkboxes), [Control](/docs/api/form/control), [Field](/docs/api/form/field), [File](/docs/api/form/file), [Input](/docs/api/form/input), [Numberinput](/docs/api/form/numberinput), [Radio](/docs/api/form/radio), [Radios](/docs/api/form/radios), [Rate](/docs/api/form/rate), [Select](/docs/api/form/select), [Slider](/docs/api/form/slider), [Switch](/docs/api/form/switch), [Taginput](/docs/api/form/taginput), [TextArea](/docs/api/form/textarea)

`Input`, `Select`, and `TextArea` accept `label`, icon, and `message` props to auto-wrap with `Field` + `Control`. For complex layouts, use the raw `InputBase`, `SelectBase`, and `TextAreaBase` primitives.

```tsx live
function FormShowcase() {
  const [on, setOn] = React.useState(true);
  return (
    <Columns>
      <Column>
        <Field label="Name">
          <Input placeholder="Jane Doe" />
        </Field>
      </Column>
      <Column>
        <Field label="Role">
          <Select>
            <option>Developer</option>
            <option>Designer</option>
            <option>Manager</option>
          </Select>
        </Field>
      </Column>
      <Column isNarrow>
        <Field label="Active">
          <Switch
            checked={on}
            onChange={e => setOn(e.target.checked)}
            color="success"
            isRounded
          >
            {on ? 'Yes' : 'No'}
          </Switch>
        </Field>
      </Column>
    </Columns>
  );
}
```

[Browse all Form components &rarr;](/docs/guides/library/form)

---

## Columns & Grid

:::info Two layout systems
**Columns** is Bulma's classic 12-column flexbox system — great for most layouts. **Grid** is the new CSS-grid system in Bulma v1 — ideal for complex, auto-responsive layouts.
:::

**Columns** — classic flexbox:

```tsx live
<Columns>
  <Column size="one-quarter">
    <Notification color="primary" textAlign="centered">
      1/4
    </Notification>
  </Column>
  <Column>
    <Notification color="link" textAlign="centered">
      Auto
    </Notification>
  </Column>
  <Column size="one-quarter">
    <Notification color="primary" textAlign="centered">
      1/4
    </Notification>
  </Column>
</Columns>
```

**Grid** — CSS-grid with auto-responsive cells:

```tsx live
<Grid minCol={8} gap={3}>
  <Cell>
    <Notification color="success" textAlign="centered">
      1
    </Notification>
  </Cell>
  <Cell colSpan={2}>
    <Notification color="warning" textAlign="centered">
      span 2
    </Notification>
  </Cell>
  <Cell>
    <Notification color="success" textAlign="centered">
      3
    </Notification>
  </Cell>
  <Cell>
    <Notification color="info" textAlign="centered">
      4
    </Notification>
  </Cell>
  <Cell>
    <Notification color="info" textAlign="centered">
      5
    </Notification>
  </Cell>
</Grid>
```

[View Columns API &rarr;](/docs/api/columns) &nbsp;|&nbsp; [View Grid API &rarr;](/docs/api/grid)

---

## Layout (6)

Page-level structural primitives.

[Container](/docs/api/layout/container), [Footer](/docs/api/layout/footer), [Hero](/docs/api/layout/hero), [Level](/docs/api/layout/level), [Media](/docs/api/layout/media), [Section](/docs/api/layout/section)

```tsx live
<Hero color="info" size="small">
  <Hero.Body>
    <Title>Hero Banner</Title>
    <SubTitle>Page-level layout components give your app structure.</SubTitle>
  </Hero.Body>
</Hero>
```

[View Layout API &rarr;](/docs/api/layout/container)

---

## Helpers

Utilities for working with Bulma classes and configuration:

- **useBulmaClasses** — a React hook that converts helper props into Bulma class strings
- **classNames** — a lightweight class-merging utility
- **Theme** — a component that injects Bulma CSS variables for local or global theming
- **ConfigProvider** — a context provider for global settings like class prefix and icon library

[View Helpers API &rarr;](/docs/api/helpers/usebulmaclasses)

---

## Extras — free forever

:::tip 🍺 Free as in beer
Every component in this library — including all extras — is free and always will be. No premium tier, no paywall.
:::

Beyond the core Bulma wrappers, bestax-bulma ships additional components that fill gaps where Bulma doesn't provide a built-in solution:

| Category       | Extras                                                              |
| -------------- | ------------------------------------------------------------------- |
| **Components** | Carousel, Steps, Dialog, Toast, Sidebar, Loading, Tooltip, Collapse |
| **Form**       | Autocomplete, Switch, Slider, Numberinput, Rate, Taginput           |
| **Elements**   | LinkButton                                                          |

These extras include purpose-built SCSS that follows Bulma v1's CSS-variable conventions, so they theme and customise exactly like native Bulma components. They're bundled into `bestax.css` — no separate import needed.

---

## Layout Components Overview

# Layout Components

This page summarizes all Bulma-styled layout components in Bestax, with a brief description, usage example, and links to full documentation for each. Use these components to structure your app with responsive, flexible, and visually consistent layouts.

---

## Container

A responsive layout wrapper for centering and constraining content. Supports fixed/fluid layouts, breakpoints, and color helpers.

```tsx live
<Container>
  <Notification color="primary">Content goes here.</Notification>
</Container>
```

[View full documentation.](../../api/layout/container)

---

## Hero

A visually striking section for headers, banners, or landing areas. Supports color, size, fullheight, and composition with `Hero.Head`, `Hero.Body`, and `Hero.Foot`.

```tsx live
<Hero color="link">
  <Hero.Body>
    <Container>
      <Title>Hero title</Title>
      <SubTitle>Hero subtitle</SubTitle>
    </Container>
  </Hero.Body>
</Hero>
```

[View full documentation.](../../api/layout/hero)

---

## Footer

A semantic, accessible site footer for copyright, links, or extra info. Supports color, background, and custom content.

```tsx live
<Footer backgroundColor="dark">
  <Content textAlign="centered">
    Copyright © 2025 Bestax-Bulma
  </Content>
</Footer>
```

[View full documentation.](../../api/layout/footer)

---

## Level

A flexible horizontal layout for aligning items left, right, or center. Use for toolbars, status bars, or summary sections. Includes `Level.Left`, `Level.Right`, and `Level.Item` subcomponents.

```tsx live
<Level>
  <Level.Left>
    <Level.Item>
      <Title as="p" size="5" className="subtitle">
        Stats
      </Title>
    </Level.Item>
  </Level.Left>
  <Level.Right>
    <Level.Item>Right content</Level.Item>
  </Level.Right>
</Level>
```

[View full documentation.](../../api/layout/level)

---

## Section

Provides vertical spacing and visual separation for large blocks of content. Supports size, color, and background helpers.

```tsx live
<Section>
  <Title>Section</Title>
  <SubTitle>Divide your content into sections.</SubTitle>
</Section>
```

[View full documentation.](../../api/layout/section)

---

## Media

Implements Bulma’s media object layout for aligning images/icons with content and actions. Includes `Media.Left`, `Media.Content`, and `Media.Right` subcomponents.

```tsx live
<Media>
  <Media.Left>
    <Image src="/img/logo.svg" size="64x64" />
  </Media.Left>
  <Media.Content>
    
      Bestax Bulma <small>@allxsmith/bestax</small>{' '}
      <small>TS</small>
      
      Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam ultricies
      nisi neque, eu accumsan dui tempus id. Nunc fringilla, est at tincidunt
      iaculis, diam dui aliquet magna, in imperdiet leo lorem eget augue.
      Pellentesque vel nisl non sem condimentum elementum non sed nibh. Donec
      venenatis a diam a tempor.
    
  </Media.Content>
  <Media.Right>
    <Delete />
  </Media.Right>
</Media>
```

[View full documentation.](../../api/layout/media)

---

For more details and advanced usage, see the full documentation for each component linked above.

---

## LLMs

# bestax-bulma with LLMs

`@allxsmith/bestax-bulma` ships LLM-optimized documentation so AI coding agents —
Claude Code, Cursor, GitHub Copilot, ChatGPT — can read the docs in full and build
with the library correctly. This page explains what's published and how to use it.

## Using bestax docs with AI tools

Point your assistant at the docs — the approach is the same across Claude Code,
Cursor, Copilot, and ChatGPT:

- **Give it the index.** Add `https://bestax.io/llms.txt` to your project docs / rules,
  or paste it into the chat, so the model can discover every page and fetch what it needs.
- **Feed it everything.** For a one-shot load of the whole library, use
  `https://bestax.io/llms-full.txt`.
- **Fetch a single page.** For a focused question, link the page's Markdown directly —
  e.g. `https://bestax.io/docs/api/elements/button.md` — to keep the context small.

## Skills

Beyond the raw docs, bestax ships **Agent Skills** that teach an agent _how_ to build
with the library (conventions, patterns, and a component catalog). Install one with the
[`skills`](https://skills.sh/) CLI:

```bash
npx skills add https://github.com/allxsmith/bestax --skill bestax-custom-component
npx skills add https://github.com/allxsmith/bestax --skill bestax-form
npx skills add https://github.com/allxsmith/bestax --skill bestax-theming
npx skills add https://github.com/allxsmith/bestax --skill bestax-layout-scaffold
```

Starting a new app? `pnpm create bestax@latest` offers to **preinstall these skills**
into the generated app's `.claude/skills/` (alongside a `CLAUDE.md`), so a Claude Code
session picks them up automatically. See the [Skills overview](/docs/skills/intro) for
what each one does.

## MCP server (coming soon)

A first-party bestax **MCP server** — for querying components, props, and examples
directly from an MCP-compatible client — is planned. This page will document it once it
ships. (bestax will provide its own server; it does not rely on a third-party one.)

## Contributing

Found the LLM docs unclear, incomplete, or wrong for your agent? Please
[open an issue](https://github.com/allxsmith/bestax/issues/new/choose) describing what
you expected and what happened — feedback on how well the docs work with AI tools is
especially welcome.

## How these docs are generated

The LLM docs are generated at build time by
[`docusaurus-plugin-llms`](https://github.com/rachfop/docusaurus-plugin-llms)
(configured in `docs/docusaurus.config.js`), following the
[llmstxt.org](https://llmstxt.org) standard. Three artifacts are produced and served
from the site root:

| File                                                | What it is                                                                                                                          |
| --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| [`/llms.txt`](https://bestax.io/llms.txt)           | Curated **index** — a table of contents linking every doc page (per the llmstxt.org spec).                                          |
| [`/llms-full.txt`](https://bestax.io/llms-full.txt) | The **entire documentation** concatenated into a single plain-text file.                                                            |
| Per-page `.md`                                      | Every page is also served as clean Markdown at `<page>.md`, e.g. [`/docs/guides/intro.md`](https://bestax.io/docs/guides/intro.md). |

All three are regenerated on every docs build, so they always match the deployed site.

---

## Quick Start(Docs)


Get **bestax-bulma** running in under 2 minutes with this quick start guide.

:::tip
For detailed installation options, framework-specific guides, or troubleshooting, check out our [comprehensive guides](/docs/guides/getting-started/installation).
:::

---

## 1. Run the Installer

```bash
pnpm create bestax@latest my-bestax-app
cd my-bestax-app
```

The installer walks you through a few prompts and sets up everything for you:

- **Framework** — Vite (JavaScript) or Vite + TypeScript
- **Bulma flavor** — Complete, Prefixed, No Helpers, No Helpers + Prefixed, or No Dark Mode
- **Icon library** — Font Awesome, Material Design Icons, Material Icons, Material Symbols, Ionicons, or none

It installs `@allxsmith/bestax-bulma`, the icon font package you pick, adds the CSS imports to `src/main.{jsx,tsx}`, and scaffolds a working app. No manual `pnpm install` or CSS import step needed.

---

## 2. Edit Your First Component

Open `src/App.jsx` (or `App.tsx`) and replace it with:

```jsx

function App() {
  const [showAlert, setShowAlert] = useState(false);

  return (
    <Box>
      <Title>Welcome to bestax-bulma! 🎉</Title>

      <Button color="primary" onClick={() => setShowAlert(!showAlert)}>
        Click me!
      </Button>

      {showAlert && (
        <Notification color="success" mt="4">
          Great! You're ready to build with bestax-bulma.
        </Notification>
      )}
    </Box>
  );
}

export default App;
```

---

## 3. Run Your App

```bash
pnpm dev
```

**That's it!** Visit http://localhost:5173 to see your app running.

---

## What's Next?

Now that you have bestax-bulma running:

### 📦 **Installation Options**

→ [Installation Guide](/docs/guides/getting-started/installation)

- Different ways to include Bulma CSS
- Adding icon libraries (Font Awesome, Material Icons)
- Prerequisites and browser support

### 🛠️ **Toolchain Setup**

→ [Toolchains](/docs/guides/getting-started/react-setups)

- Next.js setup (with SSR)
- TypeScript configuration
- Create React App setup
- Vite advanced configuration

### 🎨 **Explore Components**

→ [Browse all components](/docs/category/elements)

- 80+ React components
- Full Bulma v1 support
- Live examples and API docs

---

## Component Categories

bestax-bulma provides a complete set of Bulma components organized into logical groups:

### 🟢 [Elements](/docs/category/elements)

Basic building blocks like [Button](/docs/api/elements/button), [Box](/docs/api/elements/box), [Title](/docs/api/elements/title), and [Tag](/docs/api/elements/tag).

### 🟦 [Layout](/docs/category/layout)

Structure your app with [Container](/docs/api/layout/container), [Section](/docs/api/layout/section), [Hero](/docs/api/layout/hero), and [Level](/docs/api/layout/level).

### 🟧 [Components](/docs/category/components)

Advanced UI components like [Modal](/docs/api/components/modal), [Navbar](/docs/api/components/navbar), [Carousel](/docs/api/components/carousel), and [Dialog](/docs/api/components/dialog).

### 🟪 [Form](/docs/category/form)

Complete form controls including [Input](/docs/api/form/input), [Select](/docs/api/form/select), [Autocomplete](/docs/api/form/autocomplete), and [DateInput](/docs/api/form/datetime/dateinput).

### 🟩 [Grid & Columns](/docs/category/grid)

Responsive layouts with [Grid](/docs/api/grid), [Columns](/docs/api/columns), and [Cell](/docs/api/grid/cell).

---

## Live Playground

Want to experiment? Try our live examples:

```tsx live
// Try editing this code!
function Demo() {
  const [count, setCount] = useState(0);

  return (
    <Box>
      <Title size="4">Interactive Demo</Title>
      <Buttons>
        <Button color="primary" onClick={() => setCount(count + 1)}>
          Clicked {count} times
        </Button>
        <Button color="danger" isOutlined onClick={() => setCount(0)}>
          Reset
        </Button>
      </Buttons>
    </Box>
  );
}
```

---

## Need Help?

- 📚 **[Full Documentation](/docs/guides/getting-started/installation)** - Detailed setup guides
- 🎨 **[Storybook](https://bestax.io/storybook)** - Interactive component explorer
- 💬 **[GitHub Issues](https://github.com/allxsmith/bestax/issues)** - Report bugs or request features
- 📦 **[NPM Package](https://www.npmjs.com/package/@allxsmith/bestax-bulma)** - Package details

---

## For AI Tools

Building with an AI agent? bestax-bulma ships LLM-optimized docs:

- 🤖 **[LLMs guide](/docs/guides/llms)** - How to use the library with Claude Code, Cursor, and Copilot
- 📄 **[llms.txt](https://bestax.io/llms.txt)** / **[llms-full.txt](https://bestax.io/llms-full.txt)** - Point your assistant straight at the docs
- 🧩 **[Agent Skills](/docs/skills/intro)** - `npx skills add https://github.com/allxsmith/bestax --skill bestax-layout-scaffold`

---

## Why bestax-bulma?

- ✅ **Latest Bulma v1** - Full support for the newest Bulma features
- ✅ **TypeScript Ready** - Complete type definitions included
- ✅ **Tree Shakeable** - Only import what you need
- ✅ **99% Test Coverage** - Reliable and stable
- ✅ **Just One Dependency** - Bulma. Every Bulma library depends on it — we bundle it for you

---

## Congratulations!


You have just learned the **basics of Docusaurus** and made some changes to the **initial template**.

Docusaurus has **much more to offer**!

Have **5 more minutes**? Take a look at **[versioning](../tutorial-extras/manage-docs-versions.md)** and **[i18n](../tutorial-extras/translate-your-site.md)**.

Anything **unclear** or **buggy** in this tutorial? [Please report it!](https://github.com/facebook/docusaurus/discussions/4610)

## What's next?

- Read the [official documentation](https://docusaurus.io/)
- Modify your site configuration with [`docusaurus.config.js`](https://docusaurus.io/docs/api/docusaurus-config)
- Add navbar and footer items with [`themeConfig`](https://docusaurus.io/docs/api/themes/configuration)
- Add a custom [Design and Layout](https://docusaurus.io/docs/styling-layout)
- Add a [search bar](https://docusaurus.io/docs/search)
- Find inspirations in the [Docusaurus showcase](https://docusaurus.io/showcase)
- Get involved in the [Docusaurus Community](https://docusaurus.io/community/support)

---

## Create a Blog Post


Docusaurus creates a **page for each blog post**, but also a **blog index page**, a **tag system**, an **RSS** feed...

## Create your first Post

Create a file at `blog/2021-02-28-greetings.md`:

```md title="blog/2021-02-28-greetings.md"
---
slug: greetings
title: Greetings!
authors:
  - name: Joel Marcey
    title: Co-creator of Docusaurus 1
    url: https://github.com/JoelMarcey
    image_url: https://github.com/JoelMarcey.png
  - name: Sébastien Lorber
    title: Docusaurus maintainer
    url: https://sebastienlorber.com
    image_url: https://github.com/slorber.png
tags: [greetings]
---

Congratulations, you have made your first post!

Feel free to play around and edit this post as much as you like.
```

A new blog post is now available at [http://localhost:3000/blog/greetings](http://localhost:3000/blog/greetings).

---

## Create a Document


Documents are **groups of pages** connected through:

- a **sidebar**
- **previous/next navigation**
- **versioning**

## Create your first Doc

Create a Markdown file at `docs/hello.md`:

```md title="docs/hello.md"
# Hello

This is my **first Docusaurus document**!
```

A new document is now available at [http://localhost:3000/docs/hello](http://localhost:3000/docs/hello).

## Configure the Sidebar

Docusaurus automatically **creates a sidebar** from the `docs` folder.

Add metadata to customize the sidebar label and position:

```md title="docs/hello.md" {1-4}
---
sidebar_label: 'Hi!'
sidebar_position: 3
---

# Hello

This is my **first Docusaurus document**!
```

It is also possible to create your sidebar explicitly in `sidebars.js`:

```js title="sidebars.js"
export default {
  tutorialSidebar: [
    'intro',
    // highlight-next-line
    'hello',
    {
      type: 'category',
      label: 'Tutorial',
      items: ['tutorial-basics/create-a-document'],
    },
  ],
};
```

---

## Create a Page


Add **Markdown or React** files to `src/pages` to create a **standalone page**:

- `src/pages/index.js` → `localhost:3000/`
- `src/pages/foo.md` → `localhost:3000/foo`
- `src/pages/foo/bar.js` → `localhost:3000/foo/bar`

## Create your first React Page

Create a file at `src/pages/my-react-page.js`:

```jsx title="src/pages/my-react-page.js"

export default function MyReactPage() {
  return (
    <Layout>
      My React page
      This is a React page
    </Layout>
  );
}
```

A new page is now available at [http://localhost:3000/my-react-page](http://localhost:3000/my-react-page).

## Create your first Markdown Page

Create a file at `src/pages/my-markdown-page.md`:

```mdx title="src/pages/my-markdown-page.md"
# My Markdown page

This is a Markdown page
```

A new page is now available at [http://localhost:3000/my-markdown-page](http://localhost:3000/my-markdown-page).

---

## Deploy your site


Docusaurus is a **static-site-generator** (also called **[Jamstack](https://jamstack.org/)**).

It builds your site as simple **static HTML, JavaScript and CSS files**.

## Build your site

Build your site **for production**:

```bash
pnpm build
```

The static files are generated in the `build` folder.

## Deploy your site

Test your production build locally:

```bash
pnpm serve
```

The `build` folder is now served at [http://localhost:3000/](http://localhost:3000/).

You can now deploy the `build` folder **almost anywhere** easily, **for free** or very small cost (read the **[Deployment Guide](https://docusaurus.io/docs/deployment)**).

---

## Markdown Features


Docusaurus supports **[Markdown](https://daringfireball.net/projects/markdown/syntax)** and a few **additional features**.

## Front Matter

Markdown documents have metadata at the top called [Front Matter](https://jekyllrb.com/docs/front-matter/):

```text title="my-doc.md"
// highlight-start
---
id: my-doc-id
title: My document title
description: My document description
slug: /my-custom-url
---
// highlight-end

## Markdown heading

Markdown text with [links](./hello.md)
```

## Links

Regular Markdown links are supported, using url paths or relative file paths.

```md
Let's see how to [Create a page](/create-a-page).
```

```md
Let's see how to [Create a page](./create-a-page.md).
```

**Result:** Let's see how to [Create a page](./create-a-page.md).

## Images

Regular Markdown images are supported.

You can use absolute paths to reference images in the static directory (`static/img/docusaurus.png`):

```md
![Docusaurus logo](/img/docusaurus.png)
```

![Docusaurus logo](/img/docusaurus.png)

You can reference images relative to the current file as well. This is particularly useful to colocate images close to the Markdown files using them:

```md
![Docusaurus logo](./img/docusaurus.png)
```

## Code Blocks

Markdown code blocks are supported with Syntax highlighting.

````md
```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
  return Hello, Docusaurus!;
}
```
````

```jsx title="src/components/HelloDocusaurus.js"
function HelloDocusaurus() {
  return Hello, Docusaurus!;
}
```

## Admonitions

Docusaurus has a special syntax to create admonitions and callouts:

```md
:::tip My tip

Use this awesome feature option

:::

:::danger Take care

This action is dangerous

:::
```

:::tip My tip

Use this awesome feature option

:::

:::danger Take care

This action is dangerous

:::

## MDX and React Components

[MDX](https://mdxjs.com/) can make your documentation more **interactive** and allows using any **React components inside Markdown**:

```jsx
export const Highlight = ({children, color}) => (
   {
      alert(`You clicked the color ${color} with label ${children}`)
    }}>
    {children}
  
);

This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !

This is <Highlight color="#1877F2">Facebook blue</Highlight> !
```

export const Highlight = ({ children, color }) => (
   {
      alert(`You clicked the color ${color} with label ${children}`);
    }}
  >
    {children}
  
);

This is <Highlight color="#25c2a0">Docusaurus green</Highlight> !

This is <Highlight color="#1877F2">Facebook blue</Highlight> !

---

## Manage Docs Versions


Docusaurus can manage multiple versions of your docs.

## Create a docs version

Release a version 1.0 of your project:

```bash
pnpm docusaurus docs:version 1.0
```

The `docs` folder is copied into `versioned_docs/version-1.0` and `versions.json` is created.

Your docs now have 2 versions:

- `1.0` at `http://localhost:3000/docs/` for the version 1.0 docs
- `current` at `http://localhost:3000/docs/next/` for the **upcoming, unreleased docs**

## Add a Version Dropdown

To navigate seamlessly across versions, add a version dropdown.

Modify the `docusaurus.config.js` file:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      items: [
        // highlight-start
        {
          type: 'docsVersionDropdown',
        },
        // highlight-end
      ],
    },
  },
};
```

The docs version dropdown appears in your navbar:

![Docs Version Dropdown](./img/docsVersionDropdown.png)

## Update an existing version

It is possible to edit versioned docs in their respective folder:

- `versioned_docs/version-1.0/hello.md` updates `http://localhost:3000/docs/hello`
- `docs/hello.md` updates `http://localhost:3000/docs/next/hello`

---

## Translate your site


Let's translate `docs/intro.md` to French.

## Configure i18n

Modify `docusaurus.config.js` to add support for the `fr` locale:

```js title="docusaurus.config.js"
export default {
  i18n: {
    defaultLocale: 'en',
    locales: ['en', 'fr'],
  },
};
```

## Translate a doc

Copy the `docs/intro.md` file to the `i18n/fr` folder:

```bash
mkdir -p i18n/fr/docusaurus-plugin-content-docs/current/

cp docs/intro.md i18n/fr/docusaurus-plugin-content-docs/current/intro.md
```

Translate `i18n/fr/docusaurus-plugin-content-docs/current/intro.md` in French.

## Start your localized site

Start your site on the French locale:

```bash
pnpm start -- --locale fr
```

Your localized site is accessible at [http://localhost:3000/fr/](http://localhost:3000/fr/) and the `Getting Started` page is translated.

:::caution

In development, you can only use one locale at a time.

:::

## Add a Locale Dropdown

To navigate seamlessly across languages, add a locale dropdown.

Modify the `docusaurus.config.js` file:

```js title="docusaurus.config.js"
export default {
  themeConfig: {
    navbar: {
      items: [
        // highlight-start
        {
          type: 'localeDropdown',
        },
        // highlight-end
      ],
    },
  },
};
```

The locale dropdown now appears in your navbar:

![Locale Dropdown](./img/localeDropdown.png)

## Build your localized site

Build your site for a specific locale:

```bash
pnpm build -- --locale fr
```

Or build your site to include all the locales at once:

```bash
pnpm build
```