Item

A versatile component for displaying content with media, title, description, and actions.

Code

import {
  BadgeCheckIcon,
  Button,
  ChevronRightIcon,
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <div className="tw:flex tw:w-full tw:max-w-md tw:flex-col tw:gap-6">
      <Item variant="outline">
        <ItemContent>
          <ItemTitle>Basic Item</ItemTitle>
          <ItemDescription>
            A simple item with title and description.
          </ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button variant="outline" size="sm">
            Action
          </Button>
        </ItemActions>
      </Item>
      <Item
        variant="outline"
        size="sm"
        render={<a className="tw:text-inherit" href="#" />}
      >
        <ItemMedia>
          <BadgeCheckIcon className="tw:size-5" />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Your profile has been verified.</ItemTitle>
        </ItemContent>
        <ItemActions>
          <ChevronRightIcon className="tw:size-4" />
        </ItemActions>
      </Item>
    </div>
  );
}

The Item component is a straightforward flex container that can house nearly any type of content. Use it to display a title, description, and actions. Group it with the ItemGroup component to create a list of items.

Composition

Use the following composition to build an Item:

ItemGroup
└── Item
    ├── ItemHeader
    ├── ItemMedia
    ├── ItemContent
    │   ├── ItemTitle
    │   └── ItemDescription
    ├── ItemActions
    └── ItemFooter

Item vs Field

Use Field if you need to display a form input such as a checkbox, input, radio, or select.

If you only need to display content such as a title, description, and actions, use Item.

Variant

Use the variant prop to change the visual style of the item.

Code

import {
  InboxIcon,
  Item,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <div className="tw:flex tw:w-full tw:max-w-md tw:flex-col tw:gap-6">
      <Item>
        <ItemMedia variant="icon">
          <InboxIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Default Variant</ItemTitle>
          <ItemDescription>
            Transparent background with no border.
          </ItemDescription>
        </ItemContent>
      </Item>
      <Item variant="outline">
        <ItemMedia variant="icon">
          <InboxIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Outline Variant</ItemTitle>
          <ItemDescription>
            Outlined style with a visible border.
          </ItemDescription>
        </ItemContent>
      </Item>
      <Item variant="muted">
        <ItemMedia variant="icon">
          <InboxIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Muted Variant</ItemTitle>
          <ItemDescription>
            Muted background for secondary content.
          </ItemDescription>
        </ItemContent>
      </Item>
    </div>
  );
}

Size

Use the size prop to change the size of the item. Available sizes are default, sm, and xs.

Code

import {
  InboxIcon,
  Item,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <div className="tw:flex tw:w-full tw:max-w-md tw:flex-col tw:gap-6">
      <Item variant="outline">
        <ItemMedia variant="icon">
          <InboxIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Default Size</ItemTitle>
          <ItemDescription>
            The standard size for most use cases.
          </ItemDescription>
        </ItemContent>
      </Item>
      <Item variant="outline" size="sm">
        <ItemMedia variant="icon">
          <InboxIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Small Size</ItemTitle>
          <ItemDescription>A compact size for dense layouts.</ItemDescription>
        </ItemContent>
      </Item>
      <Item variant="outline" size="xs">
        <ItemMedia variant="icon">
          <InboxIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Extra Small Size</ItemTitle>
          <ItemDescription>The most compact size available.</ItemDescription>
        </ItemContent>
      </Item>
    </div>
  );
}

Icon

Use ItemMedia with variant="icon" to display an icon.

Code

import {
  Button,
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
  ShieldAlertIcon,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <div className="tw:flex tw:w-full tw:max-w-lg tw:flex-col tw:gap-6">
      <Item variant="outline">
        <ItemMedia variant="icon">
          <ShieldAlertIcon />
        </ItemMedia>
        <ItemContent>
          <ItemTitle>Security Alert</ItemTitle>
          <ItemDescription>
            New login detected from unknown device.
          </ItemDescription>
        </ItemContent>
        <ItemActions>
          <Button size="sm" variant="outline">
            Review
          </Button>
        </ItemActions>
      </Item>
    </div>
  );
}

Image

Use ItemMedia with variant="image" to display an image.

Code

import {
  Item,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemMedia,
  ItemTitle,
} from "@falcon/ui-kit";

const products = [
  {
    title: "DKC 62-89",
    supplier: "Green Ridge Genetics",
    category: "Corn seed",
    quantity: "120 bags",
    image:
      "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 80 80'%3E%3Crect width='80' height='80' fill='%23d9f99d'/%3E%3Cpath d='M12 58c18-28 34-28 56-36' stroke='%233f6212' stroke-width='8' fill='none'/%3E%3C/svg%3E",
  },
  {
    title: "P512 Soybeans",
    supplier: "Prairie Seed Co.",
    category: "Soybean seed",
    quantity: "80 units",
    image:
      "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 80 80'%3E%3Crect width='80' height='80' fill='%23bae6fd'/%3E%3Ccircle cx='30' cy='46' r='12' fill='%23075985'/%3E%3Ccircle cx='54' cy='32' r='12' fill='%23075985'/%3E%3C/svg%3E",
  },
  {
    title: "10-34-0 Starter",
    supplier: "Heartland Nutrients",
    category: "Fertilizer",
    quantity: "3,200 gal",
    image:
      "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 80 80'%3E%3Crect width='80' height='80' fill='%23fde68a'/%3E%3Cpath d='M20 60V32h40v28z' fill='%2392400e'/%3E%3C/svg%3E",
  },
];

export function Example() {
  return (
    <div className="tw:flex tw:w-full tw:max-w-md tw:flex-col tw:gap-6">
      <ItemGroup className="tw:gap-4">
        {products.map((product) => (
          <Item
            key={product.title}
            variant="outline"
            render={<a className="tw:text-inherit" href="#" />}
          >
            <ItemMedia variant="image">
              <img
                src={product.image}
                alt={product.title}
                width={32}
                height={32}
                className="tw:object-cover tw:grayscale"
              />
            </ItemMedia>
            <ItemContent>
              <ItemTitle className="tw:line-clamp-1">
                {product.title} -{" "}
                <span className="tw:text-muted-foreground">
                  {product.category}
                </span>
              </ItemTitle>
              <ItemDescription>{product.supplier}</ItemDescription>
            </ItemContent>
            <ItemContent className="tw:flex-none tw:text-center">
              <ItemDescription>{product.quantity}</ItemDescription>
            </ItemContent>
          </Item>
        ))}
      </ItemGroup>
    </div>
  );
}

Group

Use ItemGroup to group related items together.

Code

import {
  Button,
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemMedia,
  ItemTitle,
  PlusIcon,
} from "@falcon/ui-kit";

const people = [
  {
    username: "mlarsen",
    avatar:
      "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 40'%3E%3Crect width='40' height='40' fill='%23d9f99d'/%3E%3Ctext x='20' y='25' font-family='sans-serif' font-size='14' text-anchor='middle' fill='%233f6212'%3EML%3C/text%3E%3C/svg%3E",
    email: "mlarsen@example.com",
  },
  {
    username: "jvang",
    avatar:
      "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 40'%3E%3Crect width='40' height='40' fill='%23bae6fd'/%3E%3Ctext x='20' y='25' font-family='sans-serif' font-size='14' text-anchor='middle' fill='%23075985'%3EJV%3C/text%3E%3C/svg%3E",
    email: "jvang@example.com",
  },
  {
    username: "dmiller",
    avatar:
      "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 40'%3E%3Crect width='40' height='40' fill='%23fde68a'/%3E%3Ctext x='20' y='25' font-family='sans-serif' font-size='14' text-anchor='middle' fill='%2392400e'%3EDM%3C/text%3E%3C/svg%3E",
    email: "dmiller@example.com",
  },
];

export function Example() {
  return (
    <ItemGroup className="tw:max-w-sm">
      {people.map((person) => (
        <Item key={person.username} variant="outline">
          <ItemMedia variant="image" className="tw:rounded-full">
            <img src={person.avatar} alt="" className="tw:grayscale" />
          </ItemMedia>
          <ItemContent className="tw:gap-1">
            <ItemTitle>{person.username}</ItemTitle>
            <ItemDescription>{person.email}</ItemDescription>
          </ItemContent>
          <ItemActions>
            <Button
              variant="ghost"
              size="icon"
              className="tw:rounded-full"
              aria-label={`Add ${person.username}`}
            >
              <PlusIcon />
            </Button>
          </ItemActions>
        </Item>
      ))}
    </ItemGroup>
  );
}

Header

Use ItemHeader to add a header above the item content.

Code

import {
  Item,
  ItemContent,
  ItemDescription,
  ItemGroup,
  ItemHeader,
  ItemTitle,
} from "@falcon/ui-kit";

const plans = [
  {
    name: "Field Scout",
    description: "Everyday scouting and field notes.",
    image:
      "https://images.unsplash.com/photo-1650804068570-7fb2e3dbf888?q=80&w=640&auto=format&fit=crop",
    credit: "Valeria Reverdo on Unsplash",
  },
  {
    name: "Agronomy Plus",
    description: "Advanced planning and diagnostics.",
    image:
      "https://images.unsplash.com/photo-1610280777472-54133d004c8c?q=80&w=640&auto=format&fit=crop",
    credit: "Michael Oeser on Unsplash",
  },
  {
    name: "Co-op Basic",
    description: "Open access for every grower.",
    image:
      "https://images.unsplash.com/photo-1602146057681-08560aee8cde?q=80&w=640&auto=format&fit=crop",
    credit: "Cherry Laithang on Unsplash",
  },
];

export function Example() {
  return (
    <div className="tw:flex tw:w-full tw:max-w-xl tw:flex-col tw:gap-6">
      <ItemGroup className="tw:grid tw:grid-cols-3 tw:gap-4">
        {plans.map((plan) => (
          <Item key={plan.name} variant="outline">
            <ItemHeader>
              <img
                src={plan.image}
                alt={plan.name}
                width={128}
                height={128}
                className="tw:aspect-square tw:w-full tw:rounded-sm tw:object-cover"
              />
            </ItemHeader>
            <ItemContent>
              <ItemTitle>{plan.name}</ItemTitle>
              <ItemDescription>{plan.description}</ItemDescription>
            </ItemContent>
          </Item>
        ))}
      </ItemGroup>
    </div>
  );
}

Link

Use the render prop to render the item as a link. The hover and focus states will be applied to the anchor element.

Code

import {
  ChevronRightIcon,
  ExternalLinkIcon,
  Item,
  ItemActions,
  ItemContent,
  ItemDescription,
  ItemTitle,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <div className="tw:flex tw:w-full tw:max-w-md tw:flex-col tw:gap-4">
      <Item render={<a className="tw:text-inherit" href="#" />}>
        <ItemContent>
          <ItemTitle>Visit our documentation</ItemTitle>
          <ItemDescription>
            Learn how to get started with our components.
          </ItemDescription>
        </ItemContent>
        <ItemActions>
          <ChevronRightIcon className="tw:size-4" />
        </ItemActions>
      </Item>
      <Item
        variant="outline"
        render={
          <a
            className="tw:text-inherit"
            href="#"
            target="_blank"
            rel="noopener noreferrer"
          />
        }
      >
        <ItemContent>
          <ItemTitle>External resource</ItemTitle>
          <ItemDescription>
            Opens in a new tab with security attributes.
          </ItemDescription>
        </ItemContent>
        <ItemActions>
          <ExternalLinkIcon className="tw:size-4" />
        </ItemActions>
      </Item>
    </div>
  );
}

<Item render={<a href="/dashboard" />}>
  <ItemMedia variant="icon">
    <HomeIcon />
  </ItemMedia>
  <ItemContent>
    <ItemTitle>Dashboard</ItemTitle>
    <ItemDescription>Overview of your account and activity.</ItemDescription>
  </ItemContent>
</Item>

Dropdown

Code

import {
  Button,
  ChevronDownIcon,
  DropdownMenu,
  DropdownMenuContent,
  DropdownMenuGroup,
  DropdownMenuItem,
  DropdownMenuTrigger,
  Item,
  ItemContent,
  ItemDescription,
  ItemMedia,
  ItemTitle,
} from "@falcon/ui-kit";

const people = [
  {
    username: "mlarsen",
    avatar:
      "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 40'%3E%3Crect width='40' height='40' fill='%23d9f99d'/%3E%3Ctext x='20' y='25' font-family='sans-serif' font-size='14' text-anchor='middle' fill='%233f6212'%3EML%3C/text%3E%3C/svg%3E",
    email: "mlarsen@example.com",
  },
  {
    username: "jvang",
    avatar:
      "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 40'%3E%3Crect width='40' height='40' fill='%23bae6fd'/%3E%3Ctext x='20' y='25' font-family='sans-serif' font-size='14' text-anchor='middle' fill='%23075985'%3EJV%3C/text%3E%3C/svg%3E",
    email: "jvang@example.com",
  },
  {
    username: "dmiller",
    avatar:
      "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 40 40'%3E%3Crect width='40' height='40' fill='%23fde68a'/%3E%3Ctext x='20' y='25' font-family='sans-serif' font-size='14' text-anchor='middle' fill='%2392400e'%3EDM%3C/text%3E%3C/svg%3E",
    email: "dmiller@example.com",
  },
];

export function Example() {
  return (
    <DropdownMenu>
      <DropdownMenuTrigger render={<Button variant="outline" />}>
        Select <ChevronDownIcon />
      </DropdownMenuTrigger>
      <DropdownMenuContent className="tw:w-48" align="end">
        <DropdownMenuGroup>
          {people.map((person) => (
            <DropdownMenuItem key={person.username}>
              <Item size="xs" className="tw:w-full tw:p-2">
                <ItemMedia
                  variant="image"
                  className="tw:size-[--spacing(6.5)] tw:rounded-full"
                >
                  <img src={person.avatar} alt="" className="tw:grayscale" />
                </ItemMedia>
                <ItemContent className="tw:gap-0">
                  <ItemTitle>{person.username}</ItemTitle>
                  <ItemDescription className="tw:leading-none">
                    {person.email}
                  </ItemDescription>
                </ItemContent>
              </Item>
            </DropdownMenuItem>
          ))}
        </DropdownMenuGroup>
      </DropdownMenuContent>
    </DropdownMenu>
  );
}

API

Item

Represents one record, optionally within an ItemGroup. Renders a <div> element by default and accepts standard <div> props. Use render to replace the element. Items within an ItemGroup render with role="listitem".

Props

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, {}>

Allows replacing the Item element or composing it with another component.

size

size?: "xs" | "sm" | "default" | null = "default"

Controls the Item’s density.

variant

variant?: "outline" | "default" | "muted" | null = "default"

Controls the Item’s surface treatment.

ItemActions

Contains Item actions. Renders a <div> element and accepts standard <div> props.

ItemContent

Contains an Item’s primary content. Renders a <div> element and accepts standard <div> props.

ItemDescription

Provides supporting text for an Item. Renders a <p> element and accepts standard <p> props.

ItemFooter

Contains a full-width Item footer. Renders a <div> element and accepts standard <div> props.

ItemGroup

Groups Items into a list. Renders a <div> element with role="list" and accepts standard <div> props.

ItemHeader

Contains a full-width Item header. Renders a <div> element and accepts standard <div> props.

ItemMedia

Contains an Item icon or image. Renders a <div> element and accepts standard <div> props.

Props

variant

variant?: "image" | "default" | "icon" | null = "default"

Controls how the media is displayed. The icon variant sizes a nested icon automatically, so omit size on it; the image variant sizes and clips a nested image to the Item’s density.

ItemSeparator

Separates Items in an ItemGroup. Renders a horizontal <div> separator by default and accepts supported Separator props, including orientation, render, and style.

Props

className

className?: string

CSS class applied to the element.

orientation

orientation?: Orientation

The orientation of the separator. Defaults to "horizontal".

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, SeparatorState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component. Accepts a React element or a function that returns the element to render.

style

style?: React.CSSProperties | ((state: SeparatorState) => React.CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

ItemTitle

Provides an Item’s title. Renders a <div> element and accepts standard <div> props.