@ceed/ads 1.30.0 → 1.31.0

package/dist/components/inputs/PercentageInput.md

@@ -194,9 +194,7 @@ When `useMinorUnit` is `true`, the component converts between display values and
 <PercentageInput useMinorUnit={false} maxDecimalScale={2} value={20.12} />
 ```
 
-## Common Use Cases
-
-### Discount Configuration
+## Discount Configuration
 
 ```tsx
 function DiscountSetting() {
@@ -215,7 +213,7 @@ function DiscountSetting() {
 }
 ```
 
-### Tax Rate Settings
+## Tax Rate Settings
 
 ```tsx
 function TaxRateForm() {
@@ -240,7 +238,7 @@ function TaxRateForm() {
 }
 ```
 
-### Progress / Completion Tracker
+## Progress / Completion Tracker
 
 ```tsx
 function CompletionTracker({ value, onChange }) {
@@ -277,6 +275,31 @@ function CompletionTracker({ value, onChange }) {
 
 5. **Handle edge cases**: Consider what happens at boundary values (0%, 100%) and negative percentages if allowed.
 
+## Props and Customization
+
+### Key Props
+
+| Prop              | Type                                                     | Default | Description                                            |
+| ----------------- | -------------------------------------------------------- | ------- | ------------------------------------------------------ |
+| `value`           | `number`                                                 | -       | Percentage value (controlled mode)                     |
+| `defaultValue`    | `number`                                                 | -       | Initial percentage value (uncontrolled mode)           |
+| `onChange`        | `(event: { target: { name?, value?: number } }) => void` | -       | Callback when the value changes                        |
+| `useMinorUnit`    | `boolean`                                                | `false` | When true, value is in basis points (e.g., 1000 = 10%) |
+| `maxDecimalScale` | `number`                                                 | `0`     | Maximum number of decimal places                       |
+| `min`             | `number`                                                 | -       | Minimum allowed percentage value                       |
+| `max`             | `number`                                                 | -       | Maximum allowed percentage value                       |
+| `label`           | `ReactNode`                                              | -       | Form label displayed above the input                   |
+| `helperText`      | `ReactNode`                                              | -       | Helper text displayed below the input                  |
+| `error`           | `boolean`                                                | `false` | Applies danger color to indicate validation error      |
+| `required`        | `boolean`                                                | `false` | Marks the field as required                            |
+| `disabled`        | `boolean`                                                | `false` | Disables the input                                     |
+| `name`            | `string`                                                 | -       | HTML name attribute for form submission                |
+| `placeholder`     | `string`                                                 | -       | Placeholder text when the input is empty               |
+| `size`            | `'sm' \| 'md' \| 'lg'`                                   | `'md'`  | Input size                                             |
+| `sx`              | `SxProps`                                                | -       | Custom styles using the MUI system                     |
+
+> **Note**: PercentageInput also accepts all Input props and Framer Motion props.
+
 ## Accessibility
 
 - The input has proper labeling via the `label` prop, linked with `aria-labelledby`.

package/dist/components/inputs/RadioButton.md

@@ -336,9 +336,7 @@ Size
 </Box>
 ```
 
-## Common Use Cases
-
-### Survey / Questionnaire Form
+## Survey Questionnaire Form
 
 ```tsx
 function SurveyQuestion() {
@@ -363,7 +361,7 @@ function SurveyQuestion() {
 }
 ```
 
-### Payment Method Selection
+## Payment Method Selection
 
 ```tsx
 function PaymentMethodSelector() {
@@ -407,7 +405,7 @@ function PaymentMethodSelector() {
 }
 ```
 
-### Shipping Speed Selection
+## Shipping Speed Selection
 
 ```tsx
 function ShippingOptions() {
@@ -470,6 +468,29 @@ function ShippingOptions() {
 
 5. **Use vertical layout by default**: Vertical lists are easier to scan. Only use horizontal (`orientation="horizontal"`) when options are very short (e.g., segmented controls).
 
+## Props and Customization
+
+### Key Props
+
+| Prop             | Type                                                           | Default      | Description                                   |
+| ---------------- | -------------------------------------------------------------- | ------------ | --------------------------------------------- |
+| `checked`        | `boolean`                                                      | -            | Whether the radio is selected (controlled)    |
+| `defaultChecked` | `boolean`                                                      | `false`      | Initial selected state (uncontrolled)         |
+| `onChange`       | `(event: ChangeEvent<HTMLInputElement>) => void`               | -            | Callback when the state changes               |
+| `label`          | `ReactNode`                                                    | -            | Label content displayed next to the radio     |
+| `value`          | `string`                                                       | -            | Value attribute for form submission           |
+| `name`           | `string`                                                       | -            | Groups radios together for mutual exclusivity |
+| `color`          | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'primary'`  | Color scheme                                  |
+| `size`           | `'sm' \| 'md' \| 'lg'`                                         | `'md'`       | Radio button size                             |
+| `variant`        | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'outlined'` | Visual style                                  |
+| `disabled`       | `boolean`                                                      | `false`      | Disables the radio button                     |
+| `overlay`        | `boolean`                                                      | `false`      | Extends clickable area to parent container    |
+| `disableIcon`    | `boolean`                                                      | `false`      | Hides the radio icon                          |
+| `checkedIcon`    | `ReactNode`                                                    | -            | Custom icon for the checked state             |
+| `sx`             | `SxProps`                                                      | -            | Custom styles using the MUI system            |
+
+> **Note**: RadioButton also accepts all Joy UI Radio props and Framer Motion props.
+
 ## Accessibility
 
 - **Keyboard navigation**: Users can move between options using `Arrow Up` / `Arrow Down` (vertical) or `Arrow Left` / `Arrow Right` (horizontal). `Space` selects the focused option.

package/dist/components/inputs/RadioList.md

@@ -151,9 +151,7 @@ Five semantic colors are available via the `color` prop.
 </Stack>
 ```
 
-## Common Use Cases
-
-### Settings Selection
+## Settings Selection
 
 ```tsx
 function LanguageSetting() {
@@ -165,7 +163,7 @@ function LanguageSetting() {
       <RadioList
         items={[
           { label: 'English', value: 'en' },
-          { label: '한국어', value: 'ko' },
+          { label: 'Korean', value: 'ko' },
           { label: '日本語', value: 'ja' },
         ]}
         value={language}
@@ -176,7 +174,7 @@ function LanguageSetting() {
 }
 ```
 
-### Survey Options
+## Survey Options
 
 ```tsx
 function SatisfactionSurvey() {
@@ -198,7 +196,7 @@ function SatisfactionSurvey() {
 }
 ```
 
-### Dynamic Options from API
+## Dynamic Options from API
 
 ```tsx
 function RoleSelector({ roles }: { roles: { id: string; name: string }[] }) {
@@ -233,6 +231,25 @@ function RoleSelector({ roles }: { roles: { id: string; name: string }[] }) {
 
 5. **Use horizontal layout sparingly**: Horizontal orientation works well for 2–4 short options. For longer lists, vertical is more readable.
 
+## Props and Customization
+
+### Key Props
+
+| Prop           | Type                                                           | Default      | Description                                |
+| -------------- | -------------------------------------------------------------- | ------------ | ------------------------------------------ |
+| `items`        | `{ label: ReactNode; value: string }[]`                        | (required)   | Array of radio options                     |
+| `value`        | `string`                                                       | -            | Selected value (controlled mode)           |
+| `defaultValue` | `string`                                                       | -            | Initial selected value (uncontrolled mode) |
+| `onChange`     | `(event: ChangeEvent<HTMLInputElement>) => void`               | -            | Callback when selection changes            |
+| `name`         | `string`                                                       | -            | Groups radios together for form submission |
+| `disabled`     | `boolean`                                                      | `false`      | Disables all radio buttons                 |
+| `orientation`  | `'horizontal' \| 'vertical'`                                   | `'vertical'` | Layout orientation                         |
+| `size`         | `'sm' \| 'md' \| 'lg'`                                         | `'md'`       | Radio button size                          |
+| `color`        | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'primary'`  | Color scheme                               |
+| `sx`           | `SxProps`                                                      | -            | Custom styles using the MUI system         |
+
+> **Note**: RadioList also accepts all Joy UI RadioGroup props.
+
 ## Accessibility
 
 - RadioList renders a `<RadioGroup>` with `role="radiogroup"`, and each option is a `<Radio>` with `role="radio"`.

package/dist/components/inputs/RadioTileGroup.md

@@ -6,10 +6,10 @@ RadioTileGroup is a selection component that displays radio options as visually
 
 The component supports flexible layouts (horizontal, grid, vertical), icons via `startDecorator`, three sizes, and built-in form integration with `label`, `helperText`, `error`, and `required` props. It works in both controlled and uncontrolled modes.
 
-> **Form 구성 시 내장 prop 사용을 권장합니다**
+> **Using built-in props is recommended when building forms**
 >
-> 이 컴포넌트는 `label`, `helperText` 등의 Form 요소를 자체적으로 지원합니다.
-> Form을 구성할 때 Typography로 별도의 label이나 helperText를 만드는 대신, 컴포넌트의 내장 prop을 사용하세요.
+> This component provides built-in form-related props such as `label` and `helperText`.
+> When building a form, use the component's built-in props instead of creating separate labels or helper text with Typography.
 
 ```tsx
 <RadioTileGroup
@@ -363,9 +363,7 @@ Combine `required`, `error`, and `helperText` to build a complete form validatio
 </Stack>
 ```
 
-## Common Use Cases
-
-### Shipping Method Selection
+## Shipping Method Selection
 
 Display delivery options with icons so users can choose intuitively.
 
@@ -411,7 +409,7 @@ import BusinessIcon from '@mui/icons-material/Business';
 </Box>
 ```
 
-### Survey / Preference Selection
+## Survey / Preference Selection
 
 Present survey options with icons in a multi-column grid for a clear, scannable layout.
 
@@ -456,7 +454,7 @@ Present survey options with icons in a multi-column grid for a clear, scannable
 </Box>
 ```
 
-### Pricing Plan Picker
+## Pricing Plan Picker
 
 Use a vertical layout with `columns={1}` for plan or tier selection.
 
@@ -499,6 +497,40 @@ Use a vertical layout with `columns={1}` for plan or tier selection.
 
 5. **Always provide an error message.** When `error` is true, update `helperText` to explain the validation issue so users know how to fix it.
 
+## Props and Customization
+
+### Key Props
+
+| Prop           | Type                                             | Default    | Description                                |
+| -------------- | ------------------------------------------------ | ---------- | ------------------------------------------ |
+| `options`      | `RadioTileOption[]`                              | (required) | Array of radio tile options                |
+| `value`        | `T`                                              | -          | Selected value (controlled mode)           |
+| `defaultValue` | `T`                                              | -          | Initial selected value (uncontrolled mode) |
+| `onChange`     | `(event: ChangeEvent<HTMLInputElement>) => void` | -          | Callback when selection changes            |
+| `name`         | `string`                                         | -          | Groups radios together for form submission |
+| `label`        | `ReactNode`                                      | -          | Group label displayed above the tiles      |
+| `helperText`   | `ReactNode`                                      | -          | Helper text displayed below the tiles      |
+| `error`        | `boolean`                                        | `false`    | Applies error styling                      |
+| `required`     | `boolean`                                        | `false`    | Marks the field as required                |
+| `disabled`     | `boolean`                                        | `false`    | Disables all radio tiles                   |
+| `size`         | `'sm' \| 'md' \| 'lg'`                           | `'sm'`     | Tile size                                  |
+| `flex`         | `boolean`                                        | `false`    | Tiles stretch to fill available width      |
+| `columns`      | `number`                                         | -          | Fixed number of columns in grid layout     |
+| `textAlign`    | `'start' \| 'center'`                            | `'center'` | Text alignment within tiles                |
+| `useIndicator` | `boolean`                                        | `false`    | Shows a radio indicator on each tile       |
+| `sx`           | `SxProps`                                        | -          | Custom styles using the MUI system         |
+
+### RadioTileOption
+
+```tsx
+interface RadioTileOption<T = string> {
+  value: T;
+  label: ReactNode;
+  disabled?: boolean;
+  startDecorator?: ReactNode;
+}
+```
+
 ## Accessibility
 
 - RadioTileGroup renders a `<fieldset>` with a `<legend>` derived from the `label` prop, providing proper grouping for screen readers.

package/dist/components/inputs/Select.md

@@ -362,9 +362,7 @@ const numericOptions = [
 <Select options={numericOptions} defaultValue={1} />
 ```
 
-## Common Use Cases
-
-### Form with Validation
+## Form with Validation
 
 ```tsx
 import { useState } from 'react';
@@ -406,7 +404,7 @@ function UserForm() {
 }
 ```
 
-### Filter Bar
+## Filter Bar
 
 ```tsx
 import { Select, Stack } from '@ceed/ads';
@@ -448,7 +446,7 @@ function ProductFilter({ onFilterChange }) {
 }
 ```
 
-### Dependent Selects
+## Dependent Selects
 
 ```tsx
 import { useState, useMemo } from 'react';
@@ -544,6 +542,62 @@ function LocationSelect() {
 </FormControl>
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop             | Type                                                             | Default           | Description                                          |
+| ---------------- | ---------------------------------------------------------------- | ----------------- | ---------------------------------------------------- |
+| `options`        | `OptionType[]`                                                   | `[]`              | Array of options (objects or primitives)             |
+| `value`          | `InferOptionValue<OptionType> \| InferOptionValue<OptionType>[]` | -                 | Selected value(s) for controlled mode                |
+| `defaultValue`   | `InferOptionValue<OptionType> \| InferOptionValue<OptionType>[]` | -                 | Initial value for uncontrolled mode                  |
+| `onChange`       | `(event: { target: { name?, value } }, newValue) => void`        | -                 | Callback when selection changes                      |
+| `multiple`       | `boolean`                                                        | `false`           | Allow multiple selections (value becomes an array)   |
+| `label`          | `string`                                                         | -                 | Form label displayed above the select                |
+| `helperText`     | `string`                                                         | -                 | Helper text displayed below the select               |
+| `error`          | `boolean`                                                        | `false`           | Applies danger color to indicate validation error    |
+| `required`       | `boolean`                                                        | `false`           | Marks the field as required (adds asterisk to label) |
+| `disabled`       | `boolean`                                                        | `false`           | Disables the select                                  |
+| `placeholder`    | `string`                                                         | `'Choose one...'` | Placeholder text when no value is selected           |
+| `size`           | `'sm' \| 'md' \| 'lg'`                                           | `'md'`            | Select size                                          |
+| `variant`        | `'outlined' \| 'plain' \| 'solid' \| 'soft'`                     | `'outlined'`      | Visual style variant                                 |
+| `color`          | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'`   | `'neutral'`       | Color scheme                                         |
+| `startDecorator` | `ReactNode`                                                      | -                 | Content rendered before the select trigger text      |
+| `endDecorator`   | `ReactNode`                                                      | -                 | Content rendered after the select trigger text       |
+| `sx`             | `SxProps`                                                        | -                 | Custom styles using the MUI system                   |
+
+### Option Type
+
+Options can be objects or primitives:
+
+```tsx
+type OptionType =
+  | { label: string; value: string | number; disabled?: boolean; secondaryText?: string }
+  | string
+  | number;
+```
+
+### Generic Type Support
+
+Select supports TypeScript generics for type-safe value handling:
+
+```tsx
+// Type-safe with object options
+const options = [
+  { value: 1, label: 'Option 1' },
+  { value: 2, label: 'Option 2' },
+] as const;
+
+<Select<typeof options[number], false>
+  options={options}
+  onChange={(e, val) => {
+    // val is typed as number
+  }}
+/>
+```
+
+> **Note**: Select also accepts all Joy UI Select props.
+
 ## Accessibility
 
 - **Label association**: When you use the `label` prop, the component automatically connects the label to the select element via `aria-labelledby`. Always provide a label for screen reader users.

package/dist/components/inputs/Slider.md

@@ -232,9 +232,7 @@ Set `disabled` to prevent user interaction.
 </Box>
 ```
 
-## Common Use Cases
-
-### Controlled Slider
+## Controlled Slider
 
 ```tsx
 function VolumeControl() {
@@ -254,7 +252,7 @@ function VolumeControl() {
 }
 ```
 
-### Price Range Filter
+## Price Range Filter
 
 ```tsx
 function PriceRangeFilter() {
@@ -278,7 +276,7 @@ function PriceRangeFilter() {
 }
 ```
 
-### Temperature Setting
+## Temperature Setting
 
 ```tsx
 function TemperatureSetting() {
@@ -326,6 +324,29 @@ function TemperatureSetting() {
 
 5. **Set a reasonable `step`**: For large ranges (0–1000), use a step > 1 to prevent overwhelming precision. For small ranges (0–1), use decimal steps.
 
+## Props and Customization
+
+### Key Props
+
+| Prop                | Type                                                           | Default        | Description                                         |
+| ------------------- | -------------------------------------------------------------- | -------------- | --------------------------------------------------- |
+| `value`             | `number \| number[]`                                           | -              | Current value (controlled). Array for range sliders |
+| `defaultValue`      | `number \| number[]`                                           | `0`            | Initial value (uncontrolled)                        |
+| `onChange`          | `(event: Event, value: number \| number[]) => void`            | -              | Callback when the value changes                     |
+| `min`               | `number`                                                       | `0`            | Minimum allowed value                               |
+| `max`               | `number`                                                       | `100`          | Maximum allowed value                               |
+| `step`              | `number`                                                       | `1`            | Step increment between values                       |
+| `marks`             | `boolean \| { value: number; label?: string }[]`               | `false`        | Show marks on the slider track                      |
+| `valueLabelDisplay` | `'on' \| 'off' \| 'auto'`                                      | `'auto'`       | When to display the value label                     |
+| `orientation`       | `'horizontal' \| 'vertical'`                                   | `'horizontal'` | Slider orientation                                  |
+| `disabled`          | `boolean`                                                      | `false`        | Disables the slider                                 |
+| `size`              | `'sm' \| 'md' \| 'lg'`                                         | `'md'`         | Slider size                                         |
+| `color`             | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'primary'`    | Color scheme                                        |
+| `variant`           | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'solid'`      | Visual style                                        |
+| `sx`                | `SxProps`                                                      | -              | Custom styles using the MUI system                  |
+
+> **Note**: Slider also accepts all Joy UI Slider props.
+
 ## Accessibility
 
 - Slider renders with `role="slider"` and appropriate `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` attributes.

package/dist/components/inputs/Switch.md

@@ -190,9 +190,7 @@ Label
 </Stack>
 ```
 
-## Common Use Cases
-
-### Settings Panel
+## Settings Panel
 
 ```tsx
 function SettingsPanel() {
@@ -238,7 +236,7 @@ function SettingsPanel() {
 }
 ```
 
-### Theme Toggle
+## Theme Toggle
 
 ```tsx
 function ThemeToggle() {
@@ -259,7 +257,7 @@ function ThemeToggle() {
 }
 ```
 
-### Feature Flag with Status Text
+## Feature Flag with Status Text
 
 ```tsx
 function FeatureToggle() {
@@ -329,6 +327,26 @@ function FeatureToggle() {
 
 5. **Group related switches logically**: Place related switches under a shared heading and use consistent spacing to create a scannable settings layout.
 
+## Props and Customization
+
+### Key Props
+
+| Prop             | Type                                                           | Default     | Description                           |
+| ---------------- | -------------------------------------------------------------- | ----------- | ------------------------------------- |
+| `checked`        | `boolean`                                                      | -           | Whether the switch is on (controlled) |
+| `defaultChecked` | `boolean`                                                      | `false`     | Initial state (uncontrolled)          |
+| `onChange`       | `(event: ChangeEvent<HTMLInputElement>) => void`               | -           | Callback when the state changes       |
+| `disabled`       | `boolean`                                                      | `false`     | Disables the switch                   |
+| `readOnly`       | `boolean`                                                      | `false`     | Makes the switch read-only            |
+| `color`          | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'` | Color scheme when checked             |
+| `size`           | `'sm' \| 'md' \| 'lg'`                                         | `'md'`      | Switch size                           |
+| `variant`        | `'solid' \| 'soft' \| 'outlined' \| 'plain'`                   | `'solid'`   | Visual style                          |
+| `startDecorator` | `ReactNode`                                                    | -           | Content rendered before the switch    |
+| `endDecorator`   | `ReactNode`                                                    | -           | Content rendered after the switch     |
+| `sx`             | `SxProps`                                                      | -           | Custom styles using the MUI system    |
+
+> **Note**: Switch also accepts all Joy UI Switch props and Framer Motion props.
+
 ## Accessibility
 
 - **Role and state**: The Switch renders an `<input type="checkbox" role="switch">` with `aria-checked` reflecting the current state. Screen readers announce it as a switch, not a checkbox.

package/dist/components/inputs/Textarea.md

@@ -131,9 +131,7 @@ Use the `required`, `label`, and `helperText` props together to build complete f
 />
 ```
 
-## Common Use Cases
-
-### Feedback Form
+## Feedback Form
 
 ```tsx
 import { Textarea, Button, Stack } from '@ceed/ads';
@@ -160,7 +158,7 @@ function FeedbackForm() {
 }
 ```
 
-### Error State with Validation
+## Textarea Validation Error State
 
 ```tsx
 import { Textarea } from '@ceed/ads';
@@ -183,7 +181,7 @@ function ValidatedTextarea() {
 }
 ```
 
-### Disabled Read-Only Display
+## Disabled Read-Only Textarea
 
 ```tsx
 import { Textarea } from '@ceed/ads';
@@ -259,6 +257,30 @@ function ReadOnlyNotes() {
 <Textarea placeholder="Type here" />
 ```
 
+## Props and Customization
+
+### Key Props
+
+| Prop           | Type                                                           | Default      | Description                                       |
+| -------------- | -------------------------------------------------------------- | ------------ | ------------------------------------------------- |
+| `label`        | `string`                                                       | -            | Form label displayed above the textarea           |
+| `helperText`   | `ReactNode`                                                    | -            | Helper text displayed below the textarea          |
+| `error`        | `boolean`                                                      | `false`      | Applies danger color to indicate validation error |
+| `minRows`      | `number`                                                       | `2`          | Minimum number of visible text rows               |
+| `maxRows`      | `number`                                                       | `4`          | Maximum number of rows before scrolling           |
+| `value`        | `string`                                                       | -            | Textarea value for controlled mode                |
+| `defaultValue` | `string`                                                       | -            | Initial value for uncontrolled mode               |
+| `onChange`     | `(event: ChangeEvent<HTMLTextAreaElement>) => void`            | -            | Callback when the value changes                   |
+| `placeholder`  | `string`                                                       | -            | Placeholder text when the textarea is empty       |
+| `disabled`     | `boolean`                                                      | `false`      | Disables the textarea                             |
+| `required`     | `boolean`                                                      | `false`      | Marks the field as required                       |
+| `size`         | `'sm' \| 'md' \| 'lg'`                                         | `'md'`       | Textarea size                                     |
+| `variant`      | `'outlined' \| 'solid' \| 'soft' \| 'plain'`                   | `'outlined'` | Visual style variant                              |
+| `color`        | `'primary' \| 'neutral' \| 'danger' \| 'success' \| 'warning'` | `'neutral'`  | Color scheme                                      |
+| `sx`           | `SxProps`                                                      | -            | Custom styles using the MUI system                |
+
+> **Note**: Textarea also accepts all Joy UI Textarea props and Framer Motion props.
+
 ## Accessibility
 
 - The component automatically associates the `label` with the textarea element through FormControl, ensuring screen readers announce the label when the field receives focus.

package/dist/components/inputs/Uploader/Uploader.md

@@ -229,9 +229,7 @@ The Uploader can be disabled to prevent file selection and drag-and-drop interac
 />
 ```
 
-## Common Use Cases
-
-### Profile Photo Upload
+## Profile Photo Upload
 
 ```tsx
 import { Uploader } from '@ceed/ads';
@@ -250,7 +248,7 @@ function ProfilePhotoUpload() {
 }
 ```
 
-### Document Attachment in a Form
+## Document Attachment in a Form
 
 ```tsx
 import { Uploader, Stack, Button } from '@ceed/ads';
@@ -274,7 +272,7 @@ function DocumentForm() {
 }
 ```
 
-### Multi-Image Gallery Upload
+## Multi-Image Gallery Upload
 
 ```tsx
 import { Uploader } from '@ceed/ads';
@@ -309,6 +307,27 @@ function GalleryUpload({ existingImages }) {
 
 - **Use `minCount` with form validation.** The minimum count check triggers on form submission, not on file selection. Make sure the Uploader is inside a `<form>` element for this validation to work.
 
+## Props and Customization
+
+### Key Props
+
+| Prop               | Type                                                      | Default    | Description                                                 |
+| ------------------ | --------------------------------------------------------- | ---------- | ----------------------------------------------------------- |
+| `accept`           | `string`                                                  | (required) | Accepted file types (e.g., `'image/*'`, `'.pdf,.doc'`)      |
+| `maxFileTotalSize` | `number`                                                  | (required) | Maximum total size of all files in bytes                    |
+| `onChange`         | `(event: { target: { name?, value: File[] } }) => void`   | -          | Callback when files are added                               |
+| `onDelete`         | `(deletedFile: UserUpload) => void`                       | -          | Callback when an uploaded file is removed                   |
+| `uploaded`         | `{ id: string \| number; name: string; size?: number }[]` | -          | Pre-existing uploaded files to display                      |
+| `maxFileSize`      | `number`                                                  | -          | Maximum size per individual file in bytes                   |
+| `maxCount`         | `number`                                                  | -          | Maximum number of files allowed                             |
+| `minCount`         | `number`                                                  | -          | Minimum number of files required (validated on form submit) |
+| `label`            | `string`                                                  | -          | Label displayed above the uploader                          |
+| `helperText`       | `string`                                                  | -          | Helper text displayed below the uploader                    |
+| `error`            | `boolean`                                                 | `false`    | Applies error styling                                       |
+| `disabled`         | `boolean`                                                 | `false`    | Disables the uploader                                       |
+| `name`             | `string`                                                  | -          | HTML name attribute for form submission                     |
+| `size`             | `'sm' \| 'md'`                                            | `'md'`     | Uploader size                                               |
+
 ## Accessibility
 
 - The dropzone is keyboard-accessible and can be activated via **Enter** or **Space** to open the file browser.