# Affix (w-affix)

## Description

This component is usually used in other components like form elements to show a prefix or suffix. See for example `w-textfield`.

[Warp component reference](https://warp-ds.github.io/docs/components/text-field/frameworks/elements#prefix-label)

## Usage

`w-affix` is typically used inside form controls to render prefix/suffix text or icon actions.

### In Textfield Slots

`w-affix` is usually slotted into the w-textfield form element. Use the w-textfield's `prefix` or `suffix` slots to add the affix to the component.

```html
<w-textfield label="Price">
  <w-affix slot="suffix" label="kr"></w-affix>
</w-textfield>
```

### Text Label

Use `label` to render static text, such as currency or unit indicators.

```html
<w-affix label="kr"></w-affix>
```

### Icons

`w-affix` can also render any icon supported by `w-icon` using the attribute `icon`.

```html
<w-textfield label="Award">
  <w-affix slot="prefix" icon="AwardMedal"></w-affix>
</w-textfield>
```

### Search Icon

Use `search` to render a clickable search icon button. If you wrap the w-affix and surrounding w-textfield in a form, clicking the w-affix will submit the form.

```html
<w-affix search aria-label="Search"></w-affix>
```

### Clear Icon

Use `clear` to render a clickable clear/reset icon button.
When the clear attribute is used inside a w-textfield, clicking the clear button will automatically reset the w-textfield.

```html
<w-affix clear aria-label="Clear input"></w-affix>
```

## Accessibility

When `search` or `clear` is enabled, `w-affix` renders a button and a matching `aria-label`. If the `aria-label` incorrect for your context, you may provide your own describing the action.

```html
<w-affix search aria-label="Ad Search"></w-affix>
<w-affix clear aria-label="Clear text input"></w-affix>
```

## Examples

### Prefix Label

<elements-example>
  
```html
<w-textfield label="Price">
  <w-affix slot="suffix" label="kr"></w-affix>
</w-textfield>
```

</elements-example>

### Suffix Label

<elements-example>
  
```html
<w-textfield label="Price">
  <w-affix slot="suffix" label="kr"></w-affix>
</w-textfield>
```

</elements-example>

### Prefix Search Icon

<elements-example>
  
```html
<w-textfield label="Search">
  <w-affix slot="prefix" search></w-affix>
</w-textfield>
```

</elements-example>

### Suffix Search Icon

If you wrap the textfield with affix in a form element, clicking the search button will automatically submit the form

<elements-example>
  
```html
<form>
  <w-textfield label="Search">
    <w-affix slot="prefix" search></w-affix>
  </w-textfield>
</form>
```

</elements-example>

### Suffix Clear Icon

Clicking the clear button will reset the textfield

<elements-example>
  
```html
<w-textfield label="Search input">
  <w-affix slot="suffix" clear></w-affix>
</w-textfield>
```

</elements-example>

### Icons

<elements-example>
  
```html
<w-textfield label="Award">
  <w-affix slot="prefix" icon="AwardMedal"></w-affix>
</w-textfield>
```

</elements-example>

# Affix Styling

The affix component provides a comprehensive styling API through CSS custom properties (tokens).

## Styling API

### Wrapper Tokens

Customize the appearance of the affix wrapper container:

```css
--w-c-affix-wrapper-bg: transparent;
--w-c-affix-wrapper-border-radius: 0.4rem;
--w-c-affix-wrapper-padding-left: 1.2rem;
--w-c-affix-wrapper-padding-right: 1.2rem;
--w-c-affix-wrapper-width-with-label: max-content;
--w-c-affix-wrapper-width-with-icon: 4rem;
```

### Label Tokens

Customize the appearance of text labels (when `label` property is used):

```css
--w-c-affix-label-color: var(--w-s-color-text);
--w-c-affix-label-font-size: var(--w-font-size-xs);
--w-c-affix-label-line-height: var(--w-line-height-xs);
--w-c-affix-label-font-weight: 700;
--w-c-affix-label-cursor: default;
```

## Parts

For advanced styling needs beyond tokens, you can target internal elements using CSS parts:

- `::part(wrapper)` - The container element (either `<div>` or `<button>` depending on variant)
- `::part(label)` - The text label element (when using `label` property)

```css
w-affix::part(wrapper) {
  /* Custom styling for the wrapper */
  background-color: var(--w-s-color-background-subtle);
}

w-affix::part(label) {
  /* Custom styling for text labels */
  text-transform: uppercase;
}
```

## Example Usage

### Customizing Label Color

```css
w-affix {
  --w-c-affix-label-color: var(--w-s-color-text-primary);
}
```

### Customizing Wrapper Background

```css
w-affix {
  --w-c-affix-wrapper-bg: var(--w-s-color-background-subtle);
  --w-c-affix-wrapper-padding-left: 1.6rem;
  --w-c-affix-wrapper-padding-right: 1.6rem;
}
```

### Adjusting Icon/Label Widths

```css
w-affix {
  --w-c-affix-wrapper-width-with-icon: 5rem;
  --w-c-affix-wrapper-width-with-label: auto;
}
```

### Styling by Slot Position

Target prefix and suffix affixes differently:

```css
/* Style only prefix affixes */
w-affix[slot='prefix'] {
  --w-c-affix-wrapper-padding-left: 2rem;
}

/* Style only suffix affixes */
w-affix[slot='suffix'] {
  --w-c-affix-wrapper-padding-right: 2rem;
}
```

### Using Parts for Advanced Customization

```css
/* Add a border to the wrapper */
w-affix::part(wrapper) {
  border-left: 1px solid var(--w-s-color-border);
}

/* Make labels italic */
w-affix::part(label) {
  font-style: italic;
}
```

## `<w-affix>` API

Unless otherwise noted all properties are HTML attributes (as opposed to JavaScript object properties).

### Properties

| Name | Type | Default | Summary |
|-|-|-|-|
| _icon (JS only) | `unknown` | `-` | - |
| aria-label | `string \| null` | `null` | Accessible label for icon-button variants. |
| clear | `boolean` | `false` | Renders a clear icon button. |
| icon | `string \| null` | `null` | Icon name rendered as prefix/suffix content. |
| label | `string` | `""` | Text label shown as prefix/suffix content. |
| search | `boolean` | `false` | Renders a search icon button. |

### Property Details

#### _icon (JS only)



- Type: `unknown`
- Default: `-`

#### aria-label



- Type: `string | null`
- Default: `null`

#### clear

Add this property to render a clickable Warp close icon.

Set an `aria-label` that explains the action when using this.

- Type: `boolean`
- Default: `false`

#### icon



- Type: `string | null`
- Default: `null`

#### label



- Type: `string`
- Default: `""`

#### search

Add this property to render a clickable Warp search icon.

- Type: `boolean`
- Default: `false`