npm package: @outbook/webcomponents-form-group-radio
Description: Web components form-group-radio
Author: Antonio Rodríguez
Latest version: 1.1.4

# @outbook/webcomponents-form-group-radio

This package provides a customizable radio button group form web component.

## Installation

```bash
npm install @outbook/webcomponents-form-group-radio
```

## Usage

### As a Lit Element

```javascript
import {html} from 'lit';
import {FormGroupRadio} from '@outbook/webcomponents-form-group-radio';

function render() {
  const radioItems = [
    {value: '1', label: 'Option 1'},
    {value: '2', label: 'Option 2', isChecked: true},
    {value: '3', label: 'Option 3'}
  ];

  return html`
    ${FormGroupRadio({
    name: 'my-radio-group',
    items: radioItems,
    currentValue: '2',
    eventFn: (e) => console.log('Radio group changed:', e.currentTarget.value),
  })}
  `;
}
```

### Direct HTML Usage

You can also use the custom element directly in your HTML. Remember to import the component's JavaScript for the custom element to be defined.

```javascript
import '@outbook/webcomponents-form-group-radio';
```

```html
<outbook-form-group-radio
  name="my-radio-group"
></outbook-form-group-radio>

<script>
  const radio = document.querySelector('outbook-form-group-radio');
  radio.props = {
    items: [
      { value: 'a', label: 'Item A' },
      { value: 'b', label: 'Item B' },
    ],
    currentValue: 'a'
  };
</script>
```
Note: When using the component directly as a custom element, the properties such as `items` must be passed as a JavaScript property.

## Component: `outbook-form-group-radio`

This is the underlying web component. It can be used directly in HTML or in any framework.

### Properties for `FormGroupRadio` function

| Property           | Type      | Default     | Description                                                                                             |
|--------------------|-----------|-------------|---------------------------------------------------------------------------------------------------------|
| `name`             | `String`  | `''`        | The name for the entire radio group, shared by all radio inputs.                                        |
| `labelledby`     | `String`  | `null`      | The ID of an element that provides a label for the radio group (for accessibility).                     |
| `items`            | `Array`   | `[]`        | An array of objects, where each object represents a radio button.                                       |
| `currentValue`     | `String`  | `null`      | The value of the currently selected radio button.                                                       |
| `isVertical`       | `Boolean` | `false`     | If `true`, the radio buttons will be displayed in a vertical layout.                                    |
| `isColorSelection` | `Boolean` | `false`     | If `true`, enables a special layout for color selection.                                                |
| `isImageSelection` | `Boolean` | `false`     | If `true`, enables a special layout for image selection.                                                |
| `icons`            | `Object`  | `{}`        | An object mapping icon names to SVG literals, for use within radio items.                               |

### `item` Object Properties (in the `items` array)

| Property     | Type       | Default   | Description                                                                          |
|--------------|------------|-----------|--------------------------------------------------------------------------------------|
| `value`      | `String`   | `''`      | The value of the radio button.                                                       |
| `label`      | `String`   | `''`      | The text label for the radio button.                                                 |
| `icon`       | `String`   | `null`    | The name of an icon to display from the `icons` object.                              |
| `flag`       | `String`   | `null`    | The country code for a flag to be displayed.                                         |
| `image`      | `String`   | `null`    | The URL of an image to display.                                                      |
| `isDisabled` | `Boolean`  | `false`   | If `true`, the radio button will be disabled.                                        |
| `eventFn`    | `Function` | `null`    | A function to be called when the radio button's state changes. Receives the `change` event. |

### Events

The component does not dispatch a custom event from the group itself. Instead, you can provide an `eventFn` callback on each item, which is triggered on the native `change` event of the underlying input.

### Styling

This component uses Shadow DOM, and its styles are self-contained. The component's styles are automatically applied and encapsulated.

### Custom Properties

Can be used with css `light-dark` function.

| Custom Property                                             | Description                                                    |
|-------------------------------------------------------------|----------------------------------------------------------------|
| `--outbook-form-group-radio--item-background-color`         | The background color of a radio item.                          |
| `--outbook-form-group-radio--item-background-color--checked`| The background color of a radio item when it is selected.      |

## License

This component is licensed under the Apache-2.0 License.