# Astryx API Conventions and Prop Naming Patterns: A Complete Guide to the Design System

> Master Astryx API conventions and prop naming patterns. Discover unified size props, logical CSS for RTL, and standardized boolean prefixes. Optimize your development with this comprehensive guide.

- Repository: [Meta/astryx](https://github.com/facebook/astryx)
- Tags: api-reference
- Published: 2026-08-06

---

**Astryx components follow strict API conventions including action-prop renaming (removing the `on` prefix), unified `size` and `width` props using `SizeValue`, logical CSS properties for RTL support, and standardized boolean prefixes like `has*` and `is*`, all enforced by CLI tooling, ESLint rules, and automated codemods.**

Astryx, Facebook's open-source design system, implements a disciplined set of API conventions that make component props predictable, type-safe, and accessible across the entire library. These patterns are centrally documented in [`packages/core/CHANGELOG.md`](https://github.com/facebook/astryx/blob/main/packages/core/CHANGELOG.md) and enforced through the Astryx CLI, ESLint plugins, and codemods to ensure consistency from `Button` to `Dialog` to `Selector`.

## Action-Prop Renaming: Aligning with React 19 Conventions

Astryx has adopted the upcoming React 19 convention for action props by removing the `on` prefix. In [`packages/core/CHANGELOG.md`](https://github.com/facebook/astryx/blob/main/packages/core/CHANGELOG.md) line 1178, the migration from `on*Action` to `*Action` is documented as a breaking change that retains only the verb.

**Before:**

```tsx
<Button onChangeAction={handleClick} />

```

**After:**

```tsx
<Button changeAction={handleClick} />

```

This pattern applies to all interactive components, making event handlers more concise while maintaining clarity.

## Standardized Sizing Props: width and size

Astryx uses two distinct conventions for dimensions that appear consistently across components like `Switch`, `CheckboxInput`, `RadioList`, and `Slider`.

### The width Prop

The `width` prop follows the "input-field width" convention, accepting a `SizeValue` type where numbers are interpreted as pixels and strings are used verbatim.

```tsx
<Button
  width="100%"  // String passed directly to CSS
  width={250}   // Number interpreted as 250px
/>

```

This pattern was standardized in [`packages/core/CHANGELOG.md`](https://github.com/facebook/astryx/blob/main/packages/core/CHANGELOG.md) line 395 for the `Button` component and propagated throughout the library.

### The size Prop

The `size` prop accepts `"sm"` or `"md"` to switch between small and medium scales, as documented in line 134 of the core changelog for components like `Switch`.

```tsx
<Switch size="sm" />
<Slider size="md" />

```

## Accessibility-First Label Props

Astryx unifies accessible naming through a required or optional `label` prop that replaces `aria-label` on components exposing visible labels. According to line 332 of [`packages/core/CHANGELOG.md`](https://github.com/facebook/astryx/blob/main/packages/core/CHANGELOG.md), the `Icon` component accepts an optional `label` for screen reader accessibility.

```tsx
<Icon name="search" label="Search" />
<TextInput label="Email" />

```

Components also expose explicit accessibility props including `tooltip` and `disabledMessage` (documented in line 678) to provide human-readable context for assistive technologies.

```tsx
<TextInput
  label="Email"
  disabledMessage="Enter a valid email address"
/>

```

## Rest-Prop Forwarding and DOM Attributes

All Astryx components guarantee that consumer-provided HTML attributes reach the DOM through rest-prop forwarding. This includes `className`, `style`, `xstyle` (StyleX styles), `data-*`, and `aria-*` attributes.

In [`packages/core/CHANGELOG.md`](https://github.com/facebook/astryx/blob/main/packages/core/CHANGELOG.md) line 415, the `Button` component was updated to spread rest props before contract props, ensuring overrides work correctly:

```tsx
<Button
  changeAction={handleSubmit}
  data-testid="submit-btn"
  data-analytics-id="primary-cta"
  aria-pressed="false"
/>

```

This pattern is implemented across almost all components including `Dialog`, `CheckboxInput`, and `Selector` in `packages/core/src/*/*.tsx`.

## Logical CSS Properties for RTL Support

Astryx components use logical CSS properties instead of physical directions like `left` or `right`. The library migrated components like `Avatar` and `DropdownMenu` to use `insetInlineStart` and `insetInlineEnd` rather than directional properties, as noted in [`packages/core/CHANGELOG.md`](https://github.com/facebook/astryx/blob/main/packages/core/CHANGELOG.md) line 79.

```tsx
<TextInput
  label="Username"
  stylex={{
    paddingInline: 'var(--space-2)',  // Logical padding
    marginInlineStart: 'var(--space-1)'
  }}
/>

```

## Variant, Theme, and Status Props

Appearance customization follows predictable naming through `variant`, `elevation`, and `statusVariant` props. Line 232 of the core changelog documents the addition of `elevation="low"` to `Card` and `Button` components.

```tsx
<Card elevation="low">
  <Button variant="primary" elevation="low" />
</Card>

```

## HTML-Name Forwarding for Form Integration

Form-related components accept an `htmlName` prop to enable native form submission, as implemented in [`packages/core/CHANGELOG.md`](https://github.com/facebook/astryx/blob/main/packages/core/CHANGELOG.md) line 625 for `Switch`, `CheckboxInput`, and `RadioList`.

```tsx
<Switch htmlName="notifications" size="sm" />
<CheckboxInput htmlName="terms" label="Accept terms" />

```

## Boolean State Prop Naming

State-related props use consistent prefixes to convey intent clearly:
- **`has*`** for features (e.g., `hasClear`)
- **`is*`** for states (e.g., `isDisabled`)
- **`open*`** for visibility states

Line 32 of the changelog documents `hasClear` on the `Selector` component:

```tsx
<Selector
  options={items}
  hasClear
  isDisabled={false}
/>

```

## RTL-Aware API and Direction Handling

Astryx provides programmatic RTL support through the `useDirection()` hook and a `dir` prop on `InternationalizationProvider`, added in [`packages/core/CHANGELOG.md`](https://github.com/facebook/astryx/blob/main/packages/core/CHANGELOG.md) line 131.

```tsx
<InternationalizationProvider dir="rtl">
  <TextInput label="Name" />
</InternationalizationProvider>

```

## Tooling Enforcement: CLI, ESLint, and Codemods

These conventions are reinforced by three tooling layers defined in the source code:

### Astryx CLI

The CLI implementation in `packages/cli/clients/cli/bin/astryx.mjs` provides component API introspection. Running `astryx component <Name> --dense` outputs the full prop interface including names, types, and usage examples.

### ESLint Plugin

Rules in `packages/eslint-plugin-astryx/src/rules/*.ts` enforce naming conventions and accessibility requirements. The `@astryx/i18n-key-format` and `@astryx/no-hardcoded-i18n-string` rules ensure prop naming remains consistent and locale-aware.

### Automated Codemods

The `astryx upgrade --codemod` command automatically migrates deprecated prop patterns, such as converting `on*Action` to `*Action` or `styles` to `xstyle`, ensuring codebase consistency during version upgrades.

## Summary

- **Action props** drop the `on` prefix (e.g., `changeAction` instead of `onChangeAction`) to align with React 19 conventions.
- **Dimensions** use `width` with `SizeValue` (number for px, string for CSS) and `size` with `"sm"` or `"md"` values.
- **Accessibility** relies on `label`, `tooltip`, and `disabledMessage` props rather than direct ARIA attributes.
- **Rest props** including `data-*`, `aria-*`, `className`, and `xstyle` forward to the DOM in all components.
- **Logical CSS properties** replace directional values (`left`/`right`) for RTL compatibility.
- **Form components** accept `htmlName` for native form submission integration.
- **Boolean props** use `has*`, `is*`, and `open*` prefixes for clear intent.
- **Tooling** including the CLI (`astryx.mjs`), ESLint rules, and codemods enforce these patterns automatically.

## Frequently Asked Questions

### How do I migrate from on*Action to *Action props in Astryx?

Run `astryx upgrade --codemod` to automatically transform deprecated `on*Action` props to the new `*Action` naming convention. This codemod scans your codebase and updates event handlers like `onChangeAction` to `changeAction` across all components, as documented in [`packages/core/CHANGELOG.md`](https://github.com/facebook/astryx/blob/main/packages/core/CHANGELOG.md) line 1178.

### What is the difference between width and size in Astryx components?

The `width` prop controls the element's horizontal space using `SizeValue` (numbers become pixels, strings pass through as CSS), while `size` controls the component's visual scale using discrete tokens like `"sm"` or `"md"`. For example, `width="100%"` makes a button fill its container, whereas `size="sm"` reduces the button's padding and font size.

### How does Astryx handle RTL (right-to-left) languages in component APIs?

Astryx uses logical CSS properties (e.g., `paddingInline` instead of `paddingLeft`) and provides the `useDirection()` hook and `dir` prop on `InternationalizationProvider` to set text direction. Components automatically adjust layout based on the direction context without requiring physical directional props.

### What tooling enforces Astryx naming conventions?

The **Astryx CLI** (`packages/cli/clients/cli/bin/astryx.mjs`) displays component APIs with `astryx component <Name> --dense`. The **ESLint plugin** (`packages/eslint-plugin-astryx/src/rules/*.ts`) includes rules like `@astryx/i18n-key-format` to validate prop naming. **Codemods** automatically migrate deprecated patterns during upgrades, ensuring consistency across the codebase.