@gluonjs/atoms / packages/atoms/src / DefineUiAtomOptions

Interface: DefineUiAtomOptions<Props, TagName>

Type Parameters

Props

Props extends object

TagName

TagName extends NativeTagName

Properties

defaults?

readonly optional defaults?: Partial<Props>

displayName

readonly displayName: string

loose?

readonly optional loose?: boolean

Accepts legacy slot.content as children during incremental migrations. Ordinary children always wins when both forms are present.

nativeProps?

readonly optional nativeProps?: (props, tag) => QuarkProps<NativeElement<TagName>>

Maps the single public props object to native bindings when the component owns semantic props that must not be forwarded to the platform element. Omit this for line-neutral native wrappers.

Parameters

props

Readonly<Props>

tag

TagName

Returns

QuarkProps<NativeElement<TagName>>

style?

readonly optional style?: UiAtomStyleOptions

Creates Atom-owned style metadata without manual dependency plumbing.

tag

readonly tag: TagName | ((props) => TagName)

Example

Declare the native tag selection, defaults, optional prop mapping, migration mode, and style ownership for one concise Atom:

import { css } from '@gluonjs/core';
import {
  defineUiAtom,
  type DefineUiAtomOptions,
  type LooseUiAtomProps,
  type UiAtomBaseProps,
  type UiAtomProps,
  type UiAtomStyleOptions,
} from '@gluonjs/atoms';

interface TextLinkProps extends UiAtomBaseProps {
  readonly href?: string;
}

const style = {
  id: 'goods-text-link',
  sheet: css`:where(.goods-text-link) { text-underline-offset: 0.2em; }`,
} satisfies UiAtomStyleOptions;
const options = {
  displayName: 'TextLink',
  tag: ({ href }) => href ? 'a' : 'span',
  style,
  nativeProps: ({ href, children }, tag) => ({
    class: 'goods-text-link',
    children,
    ...(tag === 'a' ? { href } : {}),
  }),
} satisfies DefineUiAtomOptions<TextLinkProps, 'a' | 'span'>;
const TextLink = defineUiAtom(options);
const props = { href: '/shop', children: 'Shop' } satisfies UiAtomProps<TextLinkProps, 'a' | 'span'>;
const legacy = { slot: { content: 'Legacy label' } } satisfies LooseUiAtomProps;
console.log(TextLink(props), legacy.slot?.content);