engine/docs/en/UI/quickStart/transform.mdx

---
order: 1
title: UITransform
type: UI
label: UI
---

`UITransform` is a transform component specifically designed for UI elements, inheriting from the base [Transform](/apis/core/#Transform) component. It provides rich layout and alignment features and is a core component for building flexible UI systems.

## Editor Usage

When a node with UI components is added, the `UITransform` component will be automatically added (replacing the previous [Transform](/apis/core/#Transform) component). In the editor, you can select the node and use the `RectTool` (shortcut key `T`) to quickly set properties, or set precise properties in the **[Inspector Panel](/en/docs/interface/inspector)**.

### Adjusting Size and Pivot

<Image
  src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*VvXkSavtjkMAAAAAgJAAAAgAehuCAQ/original"
  style={{ zoom: "50%" }}
/>

### Setting Relative Layout

<Image
  src="https://mdn.alipayobjects.com/huamei_yo47yq/afts/img/A*gGR7TqS0aI0AAAAAgCAAAAgAehuCAQ/original"
  style={{ zoom: "50%" }}
/>

> When the main canvas's render mode is `Screen`, the editor will prohibit modifications to its `transform` to avoid screen adaptation issues. Therefore, in scripts, **developers should avoid modifying the `transform` properties of the main canvas in screen space**.

## Properties

| Property Name | Description |
| :-- | :-- |
| `size` | The size of the UI element. `x` represents width, and `y` represents height. Both default to `100` |
| `pivot` | The anchor point of the UI element. It is a normalized 2D vector with the origin at the bottom-left corner, with the default value being the center point (0.5, 0.5) |
| `horizontalAlignment` | Horizontal relative layout mode `HorizontalAlignment` |
| `alignLeft` | Distance from the parent element's left edge, effective only when `HorizontalAlignment.Left` or `HorizontalAlignment.LeftAndRight` |
| `alignRight` | Distance from the parent element's right edge, effective only when `HorizontalAlignment.Right` or `HorizontalAlignment.LeftAndRight` |
| `alignCenter` | Horizontal center offset, effective only when `HorizontalAlignment.Center` |
| `verticalAlignment` | Vertical relative layout mode `VerticalAlignment` |
| `alignTop` | Distance from the parent element's top edge, effective only when `VerticalAlignment.Top` or `VerticalAlignment.TopAndBottom` |
| `alignBottom` | Distance from the parent element's bottom edge, effective only when `VerticalAlignment.Bottom` or `VerticalAlignment.TopAndBottom` |
| `alignMiddle` | Vertical center offset, effective only when `VerticalAlignment.Middle` |

> Relative layout properties only take effect under the corresponding layout mode.

## Script Usage

### Setting Size and Pivot

```typescript
// Add canvas
const canvasEntity = root.createChild("canvas");
const canvas = canvasEntity.addComponent(UICanvas);
const imageEntity = canvasEntity.create("Image");
const uiTransform = <UITransform>imageEntity.transform;
// Set size
uiTransform.size = new Vector2(200, 100);
// Set pivot
uiTransform.pivot = new Vector2(0.5, 0.5);
```

### Setting Horizontal Relative Layout

```typescript
// Left align, 10 pixels from left edge
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Left;
uiTransform.alignLeft = 10;

// Right align, 20 pixels from right edge
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Right;
uiTransform.alignRight = 20;

// Horizontal center, offset 15 pixels to the right
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Center;
uiTransform.alignCenter = 15;

// Horizontal stretch, 30 pixels margin on both sides
uiTransform.horizontalAlignment = HorizontalAlignmentMode.LeftAndRight;
uiTransform.alignLeft = 30;
uiTransform.alignRight = 30;
```

### Setting Vertical Relative Layout

```typescript
// Top align, 10 pixels from top
uiTransform.verticalAlignment = VerticalAlignmentMode.Top;
uiTransform.alignTop = 10;

// Bottom align, 20 pixels from bottom
uiTransform.verticalAlignment = VerticalAlignmentMode.Bottom;
uiTransform.alignBottom = 20;

// Vertical center, offset 5 pixels up
uiTransform.verticalAlignment = VerticalAlignmentMode.Middle;
uiTransform.alignMiddle = 5;

// Vertical stretch, 25 pixels margin on top and bottom
uiTransform.verticalAlignment = VerticalAlignmentMode.TopAndBottom;
uiTransform.alignTop = 25;
uiTransform.alignBottom = 25;
```

## Best Practices

### Responsive Layout
Using `LeftAndRight` and `TopAndBottom` alignment modes can create responsive layouts where elements automatically adjust according to the parent container's size.

```typescript
// Create an element that always matches the parent element's size
uiTransform.horizontalAlignment = HorizontalAlignmentMode.LeftAndRight;
uiTransform.verticalAlignment = VerticalAlignmentMode.TopAndBottom;
uiTransform.alignLeft = uiTransform.alignRight = 0;
uiTransform.alignTop = uiTransform.alignBottom = 0;
```

### Performance Considerations
- Avoid frequent modifications to alignment properties as they trigger layout recalculation

## Important Notes

1. **Relative Layout Priority**: When relative layout is set, directly setting `position` will be overridden by alignment calculations
2. **Margin Effectiveness**: Each margin property only takes effect under the corresponding alignment mode
3. **Stretch Mode**: When using `LeftAndRight` or `TopAndBottom`, the corresponding direction's `size` will be automatically calculated
4. **Parent-Child Relationship**: UI alignment is based on the parent element's UITransform, ensure the parent element is also a UI element 1
title: UITransform
type: UI
label: UI
---

# UITransform Component

`UITransform` is a transform component specifically designed for UI elements in the Galacean engine, inheriting from the base `[Transform](/apis/core/#Transform)` component. It provides rich layout and alignment features and is a core component for building flexible UI systems.

## Core Features

### Size and Pivot Control
- **size**: Controls the width and height of UI elements
- **pivot**: Sets the anchor point position of UI elements, affecting the center point for rotation and scaling

### Horizontal Alignment System
UITransform provides four horizontal alignment modes:
- **Left**: Align to the left edge of the parent element
- **Center**: Center align to the horizontal center of the parent element
- **Right**: Align to the right edge of the parent element
- **LeftAndRight**: Align to both left and right edges (stretch to fill width)

### Vertical Alignment System
Similarly provides four vertical alignment modes:
- **Top**: Align to the top edge of the parent element
- **Middle**: Center align to the vertical center of the parent element
- **Bottom**: Align to the bottom edge of the parent element
- **TopAndBottom**: Align to both top and bottom edges (stretch to fill height)

## Main Properties

### Basic Properties

#### size
```typescript
get size(): Vector2
set size(value: Vector2)
```
Width and height of the UI element.

**Example:**
```typescript
// Set UI element size to 200x100
uiTransform.size = new Vector2(200, 100);
```

#### pivot
```typescript
get pivot(): Vector2
set pivot(value: Vector2)
```
Anchor point of the UI element, ranging from (0,0) to (1,1).
- (0,0) represents bottom-left corner
- (0.5,0.5) represents center point
- (1,1) represents top-right corner

**Example:**
```typescript
// Set pivot to center
uiTransform.pivot = new Vector2(0.5, 0.5);
// Set pivot to bottom-left corner
uiTransform.pivot = new Vector2(0, 0);
```

### Horizontal Alignment Properties

#### horizontalAlignment
```typescript
get horizontalAlignment(): HorizontalAlignmentMode
set horizontalAlignment(value: HorizontalAlignmentMode)
```
Horizontal alignment mode that controls the element's horizontal position within its parent container.

#### alignLeft
```typescript
get alignLeft(): number
set alignLeft(value: number)
```
Left margin, only effective when `horizontalAlignment` is `Left` or `LeftAndRight`.

#### alignRight
```typescript
get alignRight(): number
set alignRight(value: number)
```
Right margin, only effective when `horizontalAlignment` is `Right` or `LeftAndRight`.

#### alignCenter
```typescript
get alignCenter(): number
set alignCenter(value: number)
```
Horizontal center offset, only effective when `horizontalAlignment` is `Center`.
- Positive values: move right
- Negative values: move left

### Vertical Alignment Properties

#### verticalAlignment
```typescript
get verticalAlignment(): VerticalAlignmentMode
set verticalAlignment(value: VerticalAlignmentMode)
```
Vertical alignment mode that controls the element's vertical position within its parent container.

#### alignTop
```typescript
get alignTop(): number
set alignTop(value: number)
```
Top margin, only effective when `verticalAlignment` is `Top` or `TopAndBottom`.

#### alignBottom
```typescript
get alignBottom(): number
set alignBottom(value: number)
```
Bottom margin, only effective when `verticalAlignment` is `Bottom` or `TopAndBottom`.

#### alignMiddle
```typescript
get alignMiddle(): number
set alignMiddle(value: number)
```
Vertical center offset, only effective when `verticalAlignment` is `Middle`.
- Positive values: move up
- Negative values: move down

## Usage Examples

### Basic Layout Setup

```typescript
import { UITransform, HorizontalAlignmentMode, VerticalAlignmentMode } from "@galacean/engine";

// Get the Transform component of the UI element
const uiTransform = entity.getComponent(UITransform);

// Set size
uiTransform.size = new Vector2(200, 100);

// Set pivot to center
uiTransform.pivot = new Vector2(0.5, 0.5);
```

### Horizontal Alignment Examples

```typescript
// Left align, 10 pixels from left edge
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Left;
uiTransform.alignLeft = 10;

// Right align, 20 pixels from right edge
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Right;
uiTransform.alignRight = 20;

// Horizontal center, offset 15 pixels to the right
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Center;
uiTransform.alignCenter = 15;

// Horizontal stretch, 30 pixels margin on both sides
uiTransform.horizontalAlignment = HorizontalAlignmentMode.LeftAndRight;
uiTransform.alignLeft = 30;
uiTransform.alignRight = 30;
```

### Vertical Alignment Examples

```typescript
// Top align, 10 pixels from top
uiTransform.verticalAlignment = VerticalAlignmentMode.Top;
uiTransform.alignTop = 10;

// Bottom align, 20 pixels from bottom
uiTransform.verticalAlignment = VerticalAlignmentMode.Bottom;
uiTransform.alignBottom = 20;

// Vertical center, offset 5 pixels up
uiTransform.verticalAlignment = VerticalAlignmentMode.Middle;
uiTransform.alignMiddle = 5;

// Vertical stretch, 25 pixels margin on top and bottom
uiTransform.verticalAlignment = VerticalAlignmentMode.TopAndBottom;
uiTransform.alignTop = 25;
uiTransform.alignBottom = 25;
```

### Composite Alignment Examples

```typescript
// Create a UI element in the top-right corner of parent container
uiTransform.horizontalAlignment = HorizontalAlignmentMode.Right;
uiTransform.verticalAlignment = VerticalAlignmentMode.Top;
uiTransform.alignRight = 10;  // 10 pixels from right
uiTransform.alignTop = 10;    // 10 pixels from top

// Create a UI element that fills the parent container (with margins)
uiTransform.horizontalAlignment = HorizontalAlignmentMode.LeftAndRight;
uiTransform.verticalAlignment = VerticalAlignmentMode.TopAndBottom;
uiTransform.alignLeft = 20;
uiTransform.alignRight = 20;
uiTransform.alignTop = 20;
uiTransform.alignBottom = 20;
```

## Best Practices

### 1. Responsive Layout
Using `LeftAndRight` and `TopAndBottom` alignment modes can create responsive layouts where elements automatically adjust according to the parent container's size.

```typescript
// Create an element that always occupies 80% of the parent container
uiTransform.horizontalAlignment = HorizontalAlignmentMode.LeftAndRight;
uiTransform.verticalAlignment = VerticalAlignmentMode.TopAndBottom;
const margin = parentSize * 0.1; // 10% margin
uiTransform.alignLeft = margin;
uiTransform.alignRight = margin;
uiTransform.alignTop = margin;
uiTransform.alignBottom = margin;
```

### 2. Pivot Selection
Choose appropriate pivots based on the UI element's purpose:
- **Buttons**: Usually use center pivot (0.5, 0.5)
- **Text**: Choose pivot based on alignment
- **Icons**: Usually use center pivot

### 3. Performance Considerations
- Avoid frequent modifications to alignment properties as they trigger layout recalculation
- When batch updating UI, consider setting all related properties at once

## Important Notes

1. **Alignment Priority**: When alignment modes are set, directly setting `position` may be overridden by alignment calculations
2. **Margin Effectiveness**: Each margin property only takes effect under the corresponding alignment mode
3. **Stretch Mode**: When using `LeftAndRight` or `TopAndBottom`, the corresponding direction's `size` will be automatically calculated
4. **Parent-Child Relationship**: UI alignment is based on the parent element's UITransform, ensure the parent element is also a UI element

The UITransform component provides powerful and flexible UI layout capabilities for the Galacean engine. By properly using these features, you can build beautiful UI interfaces that adapt to different screen sizes.