Skip to content
ui8kit

primitive / kit

Kit Icon

UI8Kit 3 Icon primitive (unstyled), from @ui8kit/registry

Install

npx ui8kit add kit-icon

Pulls in: utils

Preview

No static preview for this item: it needs content or a parent that this page cannot supply. The code is below.

Code

Point the CLI at this runtime once, then add the item:

npx ui8kit init --yes --framework svelte --dir src --registry-url https://registry.buildy.tw/svelte --strict-cdn
npx ui8kit add kit-icon
kit/ui/icon/Icon.svelte
<!-- Code generated by @ui8kit/codegen. DO NOT EDIT. -->
<!--
  Icon renders span[data-slot=icon]; Label switches to role=img + aria-label.
-->
<script lang="ts" module>
  import type { Snippet } from "svelte";
  import type { IconSize } from "./icon.shared";

  export type IconProps = {
    size?: IconSize;
    label?: string;
    class?: string;
    children?: Snippet;
    [key: string]: unknown;
  };
</script>

<script lang="ts">
  import { iconClasses } from "./icon.shared";
  import { isSetStr, safeRest } from "../../utils/expr";

  let {
    size,
    label,
    class: className,
    children,
    ...rawRest
  }: IconProps = $props();

  const rest = $derived(safeRest(rawRest));
  const cls = $derived(iconClasses({ size, className }));
</script>

<span data-slot="icon" {...(cls ? { class: cls } : {})} aria-hidden={!(isSetStr(label)) ? "true" : undefined} role={isSetStr(label) ? "img" : undefined} aria-label={isSetStr(label) ? label : undefined} {...rest}>
  {@render children?.()}
</span>
kit/ui/icon/icon.shared.ts
// Code generated by @ui8kit/codegen. DO NOT EDIT.
// ui.icon — shared TypeScript contract (types + classes helpers)

import { cn, composeRecipe, type RecipeKey } from "../../utils";
import iconRecipeJson from "./icon.variants.json";

export const iconRecipe = iconRecipeJson;

export type IconSize = RecipeKey<typeof iconRecipe, "size">;

/** Icon renders span[data-slot=icon]; Label switches to role=img + aria-label. */
export type IconBaseProps = {
  size?: IconSize;
  label?: string;
};

export type IconClassesInput = {
  size?: IconSize;
  className?: string;
};

/** Compose Icon classes without rendering — the cross-runtime `asChild` substitute. */
export function iconClasses(input: IconClassesInput = {}): string {
  return cn(composeRecipe(iconRecipe, { size: input.size }), input.className);
}
kit/ui/icon/icon.variants.json
{
  "base": "inline-flex shrink-0 items-center justify-center",
  "byKey": {
    "size": {
      "xs": "size-3",
      "sm": "size-4",
      "md": "size-5",
      "lg": "size-6",
      "xl": "size-8"
    }
  },
  "defaults": {
    "size": "sm"
  },
  "id": "ui.icon",
  "keys": [
    "size"
  ]
}

Svelte registry item (JSON)

Point the CLI at this runtime once, then add the item:

npx ui8kit init --yes --framework react --dir src --registry-url https://registry.buildy.tw/react --strict-cdn
npx ui8kit add kit-icon
kit/ui/icon/icon.shared.ts
// Code generated by @ui8kit/codegen. DO NOT EDIT.
// ui.icon — shared TypeScript contract (types + classes helpers)

import { cn, composeRecipe, type RecipeKey } from "../../utils";
import iconRecipeJson from "./icon.variants.json";

export const iconRecipe = iconRecipeJson;

export type IconSize = RecipeKey<typeof iconRecipe, "size">;

/** Icon renders span[data-slot=icon]; Label switches to role=img + aria-label. */
export type IconBaseProps = {
  size?: IconSize;
  label?: string;
};

export type IconClassesInput = {
  size?: IconSize;
  className?: string;
};

/** Compose Icon classes without rendering — the cross-runtime `asChild` substitute. */
export function iconClasses(input: IconClassesInput = {}): string {
  return cn(composeRecipe(iconRecipe, { size: input.size }), input.className);
}
kit/ui/icon/icon.tsx
// Code generated by @ui8kit/codegen. DO NOT EDIT.
/**
 * Icon is a sized frame for a consumer-supplied glyph (svg, sprite, font).
 * No registry: the glyph is the children/slot. Decorative unless Label is set.
 */

import { forwardRef, type ReactNode, type HTMLAttributes } from "react";
import { iconClasses, type IconSize } from "./icon.shared";
import { isSetStr, safeRest } from "../../utils/expr";

/**
 * Icon renders span[data-slot=icon]; Label switches to role=img + aria-label.
 */
export type IconProps = Omit<HTMLAttributes<HTMLSpanElement>, "className" | "children" | "size" | "label"> & {
  size?: IconSize;
  label?: string;
  className?: string;
  children?: ReactNode;
};

export const Icon = forwardRef<HTMLSpanElement, IconProps>(function Icon(
  { size, label, className, children, ...rawRest },
  ref
) {
  const rest = safeRest(rawRest);
  const cls = iconClasses({ size, className });
  return (
    <span ref={ref} data-slot="icon" className={cls || undefined} aria-hidden={!(isSetStr(label)) ? "true" : undefined} role={isSetStr(label) ? "img" : undefined} aria-label={isSetStr(label) ? label : undefined} {...rest}>
      {children}
    </span>
  );
});
Icon.displayName = "Icon";
kit/ui/icon/icon.variants.json
{
  "base": "inline-flex shrink-0 items-center justify-center",
  "byKey": {
    "size": {
      "xs": "size-3",
      "sm": "size-4",
      "md": "size-5",
      "lg": "size-6",
      "xl": "size-8"
    }
  },
  "defaults": {
    "size": "sm"
  },
  "id": "ui.icon",
  "keys": [
    "size"
  ]
}

React registry item (JSON)

Point the CLI at this runtime once, then add the item:

npx ui8kit init --yes --framework vue --dir src --registry-url https://registry.buildy.tw/vue --strict-cdn
npx ui8kit add kit-icon
kit/ui/icon/Icon.vue
<!-- Code generated by @ui8kit/codegen. DO NOT EDIT. -->
<!--
  Icon renders span[data-slot=icon]; Label switches to role=img + aria-label.
-->
<script setup lang="ts">
import { computed, useAttrs } from "vue";
import { iconClasses, type IconSize } from "./icon.shared";
import { isSetStr, safeRest } from "../../utils/expr";

defineOptions({ name: "Icon", inheritAttrs: false });

const props = defineProps<{
  size?: IconSize;
  label?: string;
}>();

const attrs = useAttrs();
const callerClass = computed(() => attrs.class as string | undefined);
const restAttrs = computed(() => {
  const { class: _class, ...restEntries } = attrs;
  return safeRest(restEntries);
});
const cls = computed(() => iconClasses({ size: props.size, className: callerClass.value }));
</script>

<template>
  <span data-slot="icon" :class="cls || undefined" :aria-hidden="!(isSetStr(props.label)) ? 'true' : undefined" :role="isSetStr(props.label) ? 'img' : undefined" :aria-label="isSetStr(props.label) ? props.label : undefined" v-bind="restAttrs">
    <slot />
  </span>
</template>
kit/ui/icon/icon.shared.ts
// Code generated by @ui8kit/codegen. DO NOT EDIT.
// ui.icon — shared TypeScript contract (types + classes helpers)

import { cn, composeRecipe, type RecipeKey } from "../../utils";
import iconRecipeJson from "./icon.variants.json";

export const iconRecipe = iconRecipeJson;

export type IconSize = RecipeKey<typeof iconRecipe, "size">;

/** Icon renders span[data-slot=icon]; Label switches to role=img + aria-label. */
export type IconBaseProps = {
  size?: IconSize;
  label?: string;
};

export type IconClassesInput = {
  size?: IconSize;
  className?: string;
};

/** Compose Icon classes without rendering — the cross-runtime `asChild` substitute. */
export function iconClasses(input: IconClassesInput = {}): string {
  return cn(composeRecipe(iconRecipe, { size: input.size }), input.className);
}
kit/ui/icon/icon.variants.json
{
  "base": "inline-flex shrink-0 items-center justify-center",
  "byKey": {
    "size": {
      "xs": "size-3",
      "sm": "size-4",
      "md": "size-5",
      "lg": "size-6",
      "xl": "size-8"
    }
  },
  "defaults": {
    "size": "sm"
  },
  "id": "ui.icon",
  "keys": [
    "size"
  ]
}

Vue registry item (JSON)

Point the CLI at this runtime once, then add the item:

npx ui8kit init --yes --framework solid --dir src --registry-url https://registry.buildy.tw/solid --strict-cdn
npx ui8kit add kit-icon
kit/ui/icon/icon.shared.ts
// Code generated by @ui8kit/codegen. DO NOT EDIT.
// ui.icon — shared TypeScript contract (types + classes helpers)

import { cn, composeRecipe, type RecipeKey } from "../../utils";
import iconRecipeJson from "./icon.variants.json";

export const iconRecipe = iconRecipeJson;

export type IconSize = RecipeKey<typeof iconRecipe, "size">;

/** Icon renders span[data-slot=icon]; Label switches to role=img + aria-label. */
export type IconBaseProps = {
  size?: IconSize;
  label?: string;
};

export type IconClassesInput = {
  size?: IconSize;
  className?: string;
};

/** Compose Icon classes without rendering — the cross-runtime `asChild` substitute. */
export function iconClasses(input: IconClassesInput = {}): string {
  return cn(composeRecipe(iconRecipe, { size: input.size }), input.className);
}
kit/ui/icon/icon.solid.tsx
// Code generated by @ui8kit/codegen. DO NOT EDIT.
/**
 * Icon is a sized frame for a consumer-supplied glyph (svg, sprite, font).
 * No registry: the glyph is the children/slot. Decorative unless Label is set.
 */

import { splitProps, type JSX, type Component } from "solid-js";
import { iconClasses, type IconSize } from "./icon.shared";
import { isSetStr, safeRest } from "../../utils/expr";

/**
 * Icon renders span[data-slot=icon]; Label switches to role=img + aria-label.
 */
export type IconProps = Omit<JSX.HTMLAttributes<HTMLSpanElement>, "class" | "className" | "children" | "size" | "label"> & {
  size?: IconSize;
  label?: string;
  class?: string;
  className?: string;
  children?: JSX.Element;
};

export const Icon: Component<IconProps> = (props) => {
  const [local, rest] = splitProps(props, ["size", "label", "class", "className", "children"]);
  const cls = () => iconClasses({ size: local.size, className: local.class ?? local.className });
  return (
    <span data-slot="icon" {...(cls() ? { class: cls() } : {})} aria-hidden={!(isSetStr(local.label)) ? "true" : undefined} role={isSetStr(local.label) ? "img" : undefined} aria-label={isSetStr(local.label) ? local.label : undefined} {...safeRest(rest)}>
      {local.children}
    </span>
  );
};
kit/ui/icon/icon.variants.json
{
  "base": "inline-flex shrink-0 items-center justify-center",
  "byKey": {
    "size": {
      "xs": "size-3",
      "sm": "size-4",
      "md": "size-5",
      "lg": "size-6",
      "xl": "size-8"
    }
  },
  "defaults": {
    "size": "sm"
  },
  "id": "ui.icon",
  "keys": [
    "size"
  ]
}

Solid registry item (JSON)

Point the CLI at this runtime once, then add the item:

npx ui8kit init --yes --framework templ --dir src --registry-url https://registry.buildy.tw/templ --strict-cdn
npx ui8kit add kit-icon
ui/icon/icon.templ
// Code generated by @ui8kit/codegen. DO NOT EDIT.

/*
Icon is a sized frame for a consumer-supplied glyph (svg, sprite, font).
No registry: the glyph is the children/slot. Decorative unless Label is set.
*/

package icon

import (
	uiutils "github.com/ui8kit/codegen/generated/templ/utils"
)

// IconProps configures Icon.
type IconProps struct {
	// Size — size token: xs, sm, md, lg, xl (default sm)
	Size string
	// Class — token class names supplied by the consumer
	Class string
	// Label — accessible name; omitted = decorative (aria-hidden)
	Label string
	Attrs templ.Attributes
}

// IconClasses composes Icon classes without rendering —
// the server-composition escape hatch for custom root elements (no asChild in templ).
func IconClasses(p IconProps) string {
	return uiutils.Compose(IconVariants, map[string]string{
		"size": p.Size,
	}, p.Class)
}

// Icon renders the Icon contract.
templ Icon(p IconProps) {
	<span
		if !uiutils.HasAttr(p.Attrs, "data-slot") {
			data-slot="icon"
		}
		if IconClasses(p) != "" {
			class={ IconClasses(p) }
		}
		if !uiutils.HasAttr(p.Attrs, "aria-hidden") {
			if !uiutils.IsSetStr(p.Label) {
				aria-hidden={ "true" }
			}
		}
		if !uiutils.HasAttr(p.Attrs, "role") {
			if uiutils.IsSetStr(p.Label) {
				role={ "img" }
			}
		}
		if !uiutils.HasAttr(p.Attrs, "aria-label") {
			if uiutils.IsSetStr(p.Label) {
				aria-label={ p.Label }
			}
		}
		{ uiutils.RestAttrs(p.Attrs, false)... }
	>
		{ children... }
	</span>
}
ui/icon/icon.variants.json
{
  "base": "inline-flex shrink-0 items-center justify-center",
  "byKey": {
    "size": {
      "xs": "size-3",
      "sm": "size-4",
      "md": "size-5",
      "lg": "size-6",
      "xl": "size-8"
    }
  },
  "defaults": {
    "size": "sm"
  },
  "id": "ui.icon",
  "keys": [
    "size"
  ]
}
ui/icon/icon_gen.go
// Code generated by @ui8kit/codegen. DO NOT EDIT.

package icon

import (
	_ "embed"

	uiutils "github.com/ui8kit/codegen/generated/templ/utils"
)

//go:embed icon.variants.json
var iconVariantsJSON []byte

// IconVariants is the variant recipe shared verbatim by all runtimes.
var IconVariants = uiutils.MustParseVariantRecipe(iconVariantsJSON).ToVariants()

templ registry item (JSON)

Point the CLI at this runtime once, then add the item:

npx ui8kit init --yes --framework twig --dir src --registry-url https://registry.buildy.tw/twig --strict-cdn
npx ui8kit add kit-icon
ui/icon/Icon.html.twig
{# Code generated by @ui8kit/codegen. DO NOT EDIT. #}
{# Icon — Icon renders span[data-slot=icon]; Label switches to role=img + aria-label. #}
{# @param size (string) #}
{# @param class (string) #}
{# @param label (string) #}
{# @param attrs (attrs) #}
{# @param children (children) #}
{% set size = size|default('') %}
{% set class = class|default('') %}
{% set label = label|default('') %}
{% set attrs = attrs|default([]) %}
{% set children = children|default('') %}
<span{{ ui8kit_attrs({'data-slot': 'icon', 'class': ui8kit_or_null(ui8kit_classes('iconClasses', {'size': size, 'class': class, 'label': label})), 'aria-hidden': ((not ui8kit_is_set_str(label)) ? 'true' : null), 'role': (ui8kit_is_set_str(label) ? 'img' : null), 'aria-label': (ui8kit_is_set_str(label) ? label : null)}, attrs) }}>{{ children|raw }}</span>

Twig registry item (JSON)

Point the CLI at this runtime once, then add the item:

npx ui8kit init --yes --framework latte --dir src --registry-url https://registry.buildy.tw/latte --strict-cdn
npx ui8kit add kit-icon
ui/icon/Icon.latte
{* Code generated by @ui8kit/codegen. DO NOT EDIT. *}
{* Icon — Icon renders span[data-slot=icon]; Label switches to role=img + aria-label. *}
{parameters
  string $size = '',
  string $class = '',
  string $label = '',
  array $attrs = [],
  string $children = '',
}
<span n:attr="[
  'data-slot' => 'icon',
  'class' => \UI8Kit\Latte\Rt::orNull(\UI8Kit\Latte\Classes::iconClasses(['size' => $size, 'class' => $class, 'label' => $label])),
  'aria-hidden' => (!\UI8Kit\Latte\Rt::isSetStr($label) ? 'true' : null),
  'role' => (\UI8Kit\Latte\Rt::isSetStr($label) ? 'img' : null),
  'aria-label' => (\UI8Kit\Latte\Rt::isSetStr($label) ? $label : null),
  ...\UI8Kit\Latte\Rt::restAttrs($attrs),
]">{$children|noescape}</span>

Latte registry item (JSON)

Point the CLI at this runtime once, then add the item:

npx ui8kit init --yes --framework jinja2 --dir src --registry-url https://registry.buildy.tw/jinja2 --strict-cdn
npx ui8kit add kit-icon
ui/icon/icon.html.j2
{#- Code generated by @ui8kit/codegen. DO NOT EDIT.
    Icon: Icon renders span[data-slot=icon]; Label switches to role=img + aria-label.
    Props (p): Size (string), Class (string), Label (string), Attrs (attrs), Children (children).
    children: TRUSTED HTML printed with |safe — never pass unescaped user input.
    Classes without rendering: icon_classes(p) (no asChild in Jinja2). -#}
<span
  {%- if not ui_has_attr(ui_def(p['Attrs'], {}), 'data-slot') %} data-slot="icon"{%- endif %}
  {%- with cls = icon_classes(p) %}{%- if cls %} class="{{ cls }}"{%- endif %}{%- endwith %}
  {%- if not ui_has_attr(ui_def(p['Attrs'], {}), 'aria-hidden') %}{%- if (not ui_is_set_str(ui_def(p['Label'], ''))) %} aria-hidden="{{ 'true' }}"{%- endif %}{%- endif %}
  {%- if not ui_has_attr(ui_def(p['Attrs'], {}), 'role') %}{%- if ui_is_set_str(ui_def(p['Label'], '')) %} role="{{ 'img' }}"{%- endif %}{%- endif %}
  {%- if not ui_has_attr(ui_def(p['Attrs'], {}), 'aria-label') %}{%- if ui_is_set_str(ui_def(p['Label'], '')) %} aria-label="{{ ui_def(p['Label'], '') }}"{%- endif %}{%- endif %}
  {{ ui_attr_html(ui_def(p['Attrs'], {})) }}
>{{ children|default('', true)|safe }}</span>
ui/icon/icon.variants.json
{
  "base": "inline-flex shrink-0 items-center justify-center",
  "byKey": {
    "size": {
      "xs": "size-3",
      "sm": "size-4",
      "md": "size-5",
      "lg": "size-6",
      "xl": "size-8"
    }
  },
  "defaults": {
    "size": "sm"
  },
  "id": "ui.icon",
  "keys": [
    "size"
  ]
}

Jinja2 registry item (JSON)

Props

Names and types come from the xgen specs of the source. Standard HTML attributes (id, role, tabIndex, aria-*) pass through to the root element; the class prop is className in React.

No props data for this item.