# Customization

SvSeeds components offer flexible customization options, ranging from simple prop-based modifications to complete component overhauls.

## Using Props

### Basic Props Configuration

Each component comes with dedicated type definitions, allowing you to leverage TypeScript's type safety for customization.

```svelte
<script lang="ts">
  import { Button, type ButtonProps } from "svseeds";

  const props: ButtonProps = {
    type: "button",
    styling: "my-button",
  };
</script>

<Button {...props}>Hello</Button>
```

### Customizing Component Parts

Components that support specific parts (such as `left`, `right`, `bottom`, etc.) through props can be customized by specifying `Snippet` or `string` types for those parts. Only the specified parts will be rendered, with unnecessary elements automatically excluded.

#### Example of adding an icon to the left side:

```svelte
<script>
  import { Button } from "svseeds";
</script>

<Button>
  hello
  {#snippet left()}
    ⭐
  {/snippet}
</Button>
```

Generated HTML:

```html
<button class="svs-button whole neutral" type="button">
  <span class="svs-button left neutral">⭐</span>
  <span class="svs-button main neutral">hello</span>
</button>
```

#### Example of adding an icon to the right side:

```svelte
<script>
  import { Button } from "svseeds";
</script>

<Button {right}>hello</Button>

{#snippet right()}
  ⭐
{/snippet}
```

Generated HTML:

```html
<button class="svs-button whole neutral" type="button">
  <span class="svs-button main neutral">hello</span>
  <span class="svs-button right neutral">⭐</span>
</button>
```

### Attribute Customization

Base components accept standard HTML attributes as top-level props and forward unmatched attributes to their main element. Attributes that conflict with component-owned props or compromise component integrity may be omitted from the component type. Some wrapper or Field components expose narrower nested configuration for inner elements; check each component's documentation for those component-specific props.

```svelte
<script lang="ts">
  import { Button } from "svseeds";
</script>

<Button name="mybutton" data-testid="custom-button">Hello</Button>
```

## Advanced Usage

### Direct Element Manipulation (Element Binding)

Components with an `element` prop allow direct manipulation of the main element using `bind:element`. Check each component's documentation to see which element the `element` prop binds to.

```svelte
<script lang="ts">
  import { Button } from "svseeds";

  let element: HTMLButtonElement | undefined = $state();
  $effect(() => element?.focus());
</script>

<Button bind:element>Hello</Button>
```

### Applying Attachments

Components with an `attach` prop allow you to apply a Svelte `Attachment` to the main element. Check each component's documentation to see which element the attachment is applied to.

```svelte
<script lang="ts">
  import type { Attachment } from "svelte/attachments";
  import { Button } from "svseeds";

  const focus: Attachment<HTMLButtonElement> = (node) => {
    node.focus();

    return () => console.log("cleanup");
  };
</script>

<Button attach={focus}>hello</Button>
```

### Customizing Dependent Components

Some wrapper components render default child components for data-driven usage. They customize those generated children through a typed, namespaced configuration prop whose value is the child props minus parent-owned props.

```svelte
<script lang="ts">
  import { Accordion, type AccordionProps } from "svseeds";

  const disclosure: AccordionProps["disclosure"] = {
    styling: "my-disclosure",
  };
  const items = [{ value: "1", label: "First", panel }];
</script>

<Accordion {items} {disclosure} />

{#snippet panel(_value: string)}
  content
{/snippet}
```

## Direct Integration with CLI Tool

When you need deep customization that cannot be controlled through props, you can use the CLI tool to add components directly to your project. For details about the CLI tool, see [GitHub](https://github.com/scirexs/svseeds-cli).

### Using the CLI Tool

**npm**

```sh
npx svseeds-cli
```

**pnpm**

```sh
pnpm dlx svseeds-cli
```

**yarn**

```sh
yarn dlx svseeds-cli
```
### File Structure

By default, components are copied to the following location:

```text
project-root
└─ src
    └─ lib
        └─ _svseeds
            ├─ _Badge.svelte      # Independent component
            ├─ core.ts            # Shared functions & utilities
            └─ TagsInput.svelte   # Component with dependencies
```

File naming conventions:

- `core.ts`: Shared functions and utilities for all components
- `_` prefix: Independent components that don't depend on other SvSeeds components
- Regular files: Components that depend on other SvSeeds components (dependencies are automatically added)

### Setting Preset Styles

You can set the default style used when no `styling` prop is specified by modifying the generated `_<NAME>_PRESET` constant within the component. The value can be either a string or an `SVSClass` object.

```svelte
<script module lang="ts">
  import type { SVSClass } from "svseeds";

  export const _BUTTON_PRESET: SVSClass = "my-custom-default-style";
</script>
```