> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IconButton

> فعّل الإجراءات باستخدام أزرار أيقونات يمكن الوصول إليها.

## نظرة عامة

يُركّب `IconButton` [زر](https://docs.twenty.com/ar/ui/primitives/input/button.md) مع سطح مربع أو دائري. مرّر الأيقونة كعناصر فرعية وقدّم اسمًا متاحًا باستخدام `aria-label` أو `aria-labelledby`. محتوى الرمز زخرفي ومخفي عن التقنية المساعدة.

**Light**

[زر أيقونة باسم يمكن الوصول إليه (light)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--display\&viewMode=story\&globals=colorScheme:light)

**Dark**

[زر أيقونة باسم يمكن الوصول إليه (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--display\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-iconbutton--display)

## استخدام

```tsx theme={null}
import { IconButton } from 'twenty-ui/components/input';
import { IconSearch } from 'twenty-ui/icon';

export const SearchButton = () => (
  <IconButton aria-label="Search">
    <IconSearch />
  </IconButton>
);
```

الأحجام هي `xs` ‏(20px) و`sm` ‏(24px) و`md` ‏(32px). القيم الافتراضية هي `md` و`outline` و`neutral`. تتطابق الأنماط والألوان مع Button. استخدم `shape="round"` لزر دائري؛ الشكل الافتراضي هو `square`.

## خيارات مرئية

قارن خيارًا مرئيًا واحدًا في كل مرة. استخدم أمثلة تلميح الأدوات المسمى والمرتفع والمجمّع للتركيب.

**Light**

[متغيرات زر الأيقونة وألوانه وأحجامه وأشكاله وارتفاعه وحالاته (light)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--catalog\&viewMode=story\&globals=colorScheme:light)

**Dark**

[متغيرات زر الأيقونة وألوانه وأحجامه وأشكاله وارتفاعه وحالاته (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--catalog\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-iconbutton--catalog)

## الأسماء المتاحة

استخدم `aria-label` لاسم يُقدَّم مباشرةً على عنصر التحكم. عندما يَسمّي النص المرئي الإجراء بالفعل، استخدم `aria-labelledby` للإشارة إليه بدلًا من ذلك. مطلوب وجود خاصية تسمية واحدة على الأقل.

```tsx theme={null}
import { IconButton } from 'twenty-ui/components/input';
import { IconSearch } from 'twenty-ui/icon';
import { Text } from 'twenty-ui/primitives/typography';

export const LabelledSearchButton = () => (
  <Text style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
    <Text render={<span />} id="records-search-label">
      Search records
    </Text>
    <IconButton aria-labelledby="records-search-label" tooltip="Find a record">
      <IconSearch />
    </IconButton>
  </Text>
);
```

**Light**

[زر أيقونة يُسمّى بواسطة نص مرئي (light)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--labelled-by\&viewMode=story\&globals=colorScheme:light)

**Dark**

[زر أيقونة يُسمّى بواسطة نص مرئي (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--labelled-by\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-iconbutton--labelled-by)

## تلميح

أضف `tooltip` لإظهار النص عند التمرير والتركيز باستخدام لوحة المفاتيح. احتفظ بـ `aria-label` أو `aria-labelledby` باعتباره الاسم المتاح للإجراء. تحتفظ الأزرار المعطلة وأزرار التحميل بتلميحات التمرير.

```tsx theme={null}
import { IconButton } from 'twenty-ui/components/input';
import { IconSearch } from 'twenty-ui/icon';

export const SearchRecordsButton = () => (
  <IconButton aria-label="Search" tooltip="Search records">
    <IconSearch />
  </IconButton>
);
```

**Light**

[زر أيقونة مع تلميح (light)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--tooltip-documentation\&viewMode=story\&globals=colorScheme:light)

**Dark**

[زر أيقونة مع تلميح (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--tooltip-documentation\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-iconbutton--tooltip-documentation)

يظهر التلميح في الأسفل افتراضيًا، مع تأخير قدره 1000ms وإزاحة قدرها 5px. استخدم `tooltipPlace` و`tooltipDelay` و`tooltipOffset` لضبطه. يؤدي حذف `tooltip` إلى عرض الزر مباشرةً.

## ملكية الحالة

يوفر تطبيقك `loading` و`disabled`. كلاهما يمنع التفعيل. تحافظ حالة التحميل على الأبعاد المربعة والتسمية التي يمكن الوصول إليها. لا يتتبع الزر قيمة محددة ولا يضبط حالة التحميل تلقائيًا بعد النقر. يتبع تركيز لوحة المفاتيح الأصلي المتصفح؛ استخدم `aria-pressed` عندما يمتلك تطبيقك حالة تبديل.

## إجراءات مرتفعة

استخدم `elevated` لإضافة ظل وتمويه للخلفية. يكتسب زر المخطط المحايد الافتراضي أيضًا سطحًا ذا حدود بألوان أيقونة وتفاعل متطابقة. تحتفظ المتغيرات الأخرى والألوان الدلالية بلوحة الألوان الحالية.

القيمة الافتراضية لـ `elevated` هي `false`. لا يغيّر الموضع أو الظهور أو الحجم. يبقى الحجم `md` ‏(32px) افتراضيًا؛ عيّن `size="sm"` لعنصر تحكم بحجم 24px.

```tsx theme={null}
import { IconButton } from 'twenty-ui/components/input';
import { IconPlus } from 'twenty-ui/icon';

export const AddWidgetButton = () => (
  <IconButton elevated size="sm" aria-label="Add widget">
    <IconPlus />
  </IconButton>
);
```

**Light**

[إجراء أيقونة بارز (light)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--elevated\&viewMode=story\&globals=colorScheme:light)

**Dark**

[إجراء أيقونة بارز (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--elevated\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-iconbutton--elevated)

احذف `elevated` أو عيّنه إلى `false` لاستعادة المظهر القياسي. تدعم الأزرار البارزة تلميحات الأدوات وحالات التحميل والروابط وتفاعلات لوحة المفاتيح نفسها.

**Light**

[إجراء أيقونة بارز مع تلميح أداة (light)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--elevated-tooltip\&viewMode=story\&globals=colorScheme:light)

**Dark**

[إجراء أيقونة بارز مع تلميح أداة (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--elevated-tooltip\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-iconbutton--elevated-tooltip)

استبدل عناصر التحكم `FloatingIconButton` الحالية بـ `IconButton elevated`. مرّر الأيقونة باعتبارها children، واستخدم `aria-label` الأصلي، وحوّل `small` إلى `sm` و`medium` إلى `md`. وفّر `size="sm"` عندما كان عنصر التحكم السابق يستخدم حجمه الافتراضي. يستبدل التركيز الأصلي و`aria-pressed` التركيز الاصطناعي وعلامات الحالة النشطة.

تمت إزالة `FloatingIconButtonGroup`. ركّب ButtonGroup مع IconButton للإجراءات المجمّعة، واحتفظ بأي سطح عائم مشترك في تخطيطك.

## إجراءات مجمعة

```tsx theme={null}
import { ButtonGroup } from 'twenty-ui/primitives/input';
import { IconButton } from 'twenty-ui/components/input';
import { IconPlus, IconSearch } from 'twenty-ui/icon';

export const RecordActions = () => (
  <ButtonGroup
    aria-label="Record actions"
    size="sm"
    variant="solid"
    color="accent"
  >
    <IconButton
      aria-label="Search records"
      tooltip="Search records"
      variant="outline"
      color="neutral"
    >
      <IconSearch />
    </IconButton>
    <IconButton aria-label="Create record" tooltip="Create record">
      <IconPlus />
    </IconButton>
  </ButtonGroup>
);
```

يوفّر [ButtonGroup](https://docs.twenty.com/ar/ui/primitives/input/button-group.md) قيمًا افتراضية للحجم والمتغير واللون، بالإضافة إلى الزوايا المتجاورة. تتقدم خصائص العناصر الفرعية الصريحة بشكل مستقل، بما في ذلك `size="xs"`. لا تحتاج الأزرار الفردية إلى خاصية موضع.

أبقِ الأزرار المتصلة بالحجم نفسه لكي تصطف حوافها. عيّن الحجم للمجموعة ودَع كل زر يرثه.

**Light**

[مظهر زر الأيقونة الفردي ضمن مجموعة (light)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--grouped-overrides\&viewMode=story\&globals=colorScheme:light)

**Dark**

[مظهر زر الأيقونة الفردي ضمن مجموعة (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--grouped-overrides\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-iconbutton--grouped-overrides)

## الروابط والنماذج

من دون `render` مخصص، يعرض `href` رابط ارتساء ما لم تكن قيمة `nativeButton` هي true صراحةً. لرابط ارتساء تنقل مخصص أو رابط موجه، اضبط `nativeButton={false}` و`role="link"`. يمكن لأداة التصيير امتلاك وجهتها دون `href` لـ IconButton. أبقِ `nativeButton` بقيمة true لزر أصلي مخصص، واستخدم false لعنصر إجراء غير أصلي. تُحفظ خصائص nativeButton وrole الصريحة. لا يمكن للروابط المعطلة والتي قيد التحميل أن تُفعَّل. يبقى التوجيه داخل التطبيق.

تُمرَّر سمات الزر الأصلي ورابط الارتساء، ومعالجات الأحداث، وتفاصيل الأحداث، والمراجع، وتركيب التصيير إلى Button. يتلقى المرجع عنصر الجذر الفعلي. يحافظ تركيب تلميح الأداة على ذلك الجذر واسمه المتاح. القيمة الافتراضية هي `type="button"`؛ اضبط `type="submit"` صراحةً لإرسال النموذج.

## عناصر تحكم صغيرة ومستديرة

استخدم `size="xs"` لعنصر تحكم بحجم 20px و`shape="round"` لزوايا دائرية. تصبح عناصر التحكم `RoundedIconButton` الحالية `IconButton` مع `shape="round"` و`variant="solid"` و`color="accent"`. عيّن الحجم القديم `small` إلى `xs` والحجم `medium` إلى `sm`. وفّر عناصر فرعية للأيقونة واسمًا متاحًا.

**Light**

[أزرار أيقونات مستديرة بأحجام مدمجة وعادية (light)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--round-documentation\&viewMode=story\&globals=colorScheme:light)

**Dark**

[أزرار أيقونات مستديرة بأحجام مدمجة وعادية (dark)](https://storybook.twenty.com/iframe.html?id=ui-components-iconbutton--round-documentation\&viewMode=story\&globals=colorScheme:dark)

[Open in Storybook](https://storybook.twenty.com/?path=/story/ui-components-iconbutton--round-documentation)

## الإزاحة

**aria-label** `string`

Accessible name describing the action. Required unless `aria-labelledby` supplies the name.

**aria-labelledby** `string`

ID of the element supplying the accessible name. Can be used instead of `aria-label`.

**children** `ReactNode` *required*

Icon content. Decorative and hidden from assistive technology.

**className** `string | ((state: ButtonState) =\> string | undefined)`

CSS class applied to the element, or a function that
returns a class based on the component's state.

**color** `"accent" | "danger" | "inherit" | "neutral" | "success"` (default: neutral)

Semantic color of the button. `inherit` uses the surrounding text color for the label, icons, loader, and outline border, with translucent black interaction surfaces. It supports outline, ghost, soft, and link. Resolving solid with inherit throws, including appearance inherited from ButtonGroup and wrapper defaults.

**elevated** `boolean`

Adds a shadow and backdrop blur. Neutral outline buttons also use elevated surface colors.

**focusableWhenDisabled** `boolean` (default: false)

Whether the button should be focusable when disabled.

**href** `string`

Destination URL. Renders a native anchor when `render` is omitted unless `nativeButton` is explicitly true. Custom renderers retain their own element contract.

**loading** `boolean`

Shows a loading indicator and disables activation.

**nativeButton** `boolean` (default: true (false for the built-in href anchor))

Whether the rendered root is a native button. Defaults to true for custom renderers. The built-in `href` anchor defaults to false; an explicit value takes precedence.

**render** `ReactElement\<unknown, string | JSXElementConstructor\<any\>\> | ComponentRenderFn\<HTMLProps, ButtonState\>`

Caller-supplied root element or renderer. Native attributes, handlers, event details, and refs reach the rendered root. Use `nativeButton={false}` and `role="link"` for a custom navigation anchor. Router integration belongs to the caller.

**role** `AriaRole`

Role of the root element. Use `link` for custom navigation renderers.

**shape** `"round" | "square"` (default: square)

Square or round icon control.

**size** `"md" | "sm" | "xs"` (default: md)

Button size: `xs` (20px), `sm` (24px), or `md` (32px).

**style** `CSSProperties | ((state: ButtonState) =\> CSSProperties | undefined)`

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

**tooltip** `string`

Text displayed when hovering or focusing the button.

**tooltipDelay** `number` (default: 1000)

Delay before showing the tooltip.

**tooltipOffset** `number` (default: 5)

Distance in pixels between the button and the tooltip.

**tooltipPlace** `"bottom" | "inline-end" | "inline-start" | "left" | "right" | "top"` (default: bottom)

Preferred placement of the tooltip relative to the button.

**variant** `"ghost" | "link" | "outline" | "soft" | "solid"` (default: outline)

Visual treatment of the button surface. `link` uses compact text styling without a filled surface or border; render composition determines native semantics.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.