# `ExIcon`
[🔗](https://github.com/woylie/ex_icon/blob/1.0.0/lib/ex_icon.ex#L1)

Refer to the readme for usage instructions.

All functions of this module are internal. They are only used by
`mix ex_icon.gen.icons`.

# `options`

```elixir
@type options() :: [
  icons: [binary()] | term(),
  exclude: [binary()],
  provider: atom(),
  version: binary(),
  path: binary(),
  module_path: binary(),
  module_name: term(),
  variants: [atom()],
  global_attrs: boolean() | keyword(),
  attrs: term()
]
```

The options that every icon set in `.ex_icon.exs` takes.

* `:icons` - Required. Either a list of icon names you want to generate (e.g. `["arrow-left"]`),
  or `:all` if you want to generate all available icons.

* `:exclude` (list of `t:String.t/0`) - Icon names to skip, which is mostly useful in combination with
  `icons: :all`. Example: `["1password"]`. The default value is `[]`.

* `:provider` (`t:atom/0`) - A module implementing the `ExIcon.Provider` behaviour. Required with
  `version`, unless `path` is set.

* `:version` (`t:String.t/0`) - The release version of the icon library.

* `:path` (`t:String.t/0`) - Path to a folder that contains SVG files. Cannot be used together with
  `provider` and `version`.

* `:module_path` (`t:String.t/0`) - Required. The destination path of the icon module that ExIcon will generate
  for you. Example: `"lib/my_app_web/components/lucide.ex"`.

* `:module_name` (`t:module/0`) - Required. The name of the generated module. Example: `MyApp.Components.Lucide`.

* `:variants` (list of `t:atom/0`) - The variants of the icon library to generate, for providers that
  implement `c:ExIcon.Provider.variants/1`. Example: `[:outline, :solid]`.

  Each variant is generated into a separate module, with the variant
  appended to `module_name` and `module_path`.

  Example:

  - `module_name`: `MyApp.Components.Heroicons`
  - `module_path`: `"lib/my_app_web/components/heroicons.ex"`
  - generated module name for the `:outline` variant:
    `MyApp.Components.Heroicons.Outline`
  - path of the module for the `:outline` variant:
    `lib/my_app_web/components/heroicons/outline.ex`

  Defaults to an empty list, which generates a single module from
  `c:ExIcon.Provider.svg_folder/1`.

  Not supported if `path` is set.

  The default value is `[]`.

* `:global_attrs` - Adds an `attr :rest, :global` to the generated components, so that they
  accept the global HTML attributes, such as `id`, `class`, `phx-click` and
  `data-*`.

  Set to `true`, or to a keyword list with the `default` and `include`
  options of `attr`. Example:
  `[default: %{"class" => "size-6"}, include: ["fill"]]`.

  The attributes that are passed to a component are written before the ones
  of the SVG file, so that they take precedence.

  The default value is `false`.

* `:attrs` (list of `t:String.t/0` or `{t:String.t/0, keyword}`) - Configures the attributes of the `<svg>` element. Each entry is either an
  attribute name, or a tuple with the attribute name and options.

  If a list entry is a string (e.g. `"stroke"`), the value is replaced with
  a HEEx variable and a component attribute is added.

  If a list entry is a tuple, the following options are supported:

  - `default` (`{"stroke-width", default: "1.5"}`) - Sets the `default`
    option on `attr`.
  - `values` (`{"stroke-linecap", values: ["square", "round"]}`) - Sets the
    `values` option on `attr`. Generation fails if the value in an SVG file
    is not among the values.
  - `required` (`{"stroke-width", required: true}`) - Sets the `required`
    option on `attr`.
  - `fixed` (`{"fill", fixed: "none"}`) - Sets a fixed value for the
    SVG attribute without adding a component attribute.

  Attributes that are not present in the original SVG file are added, as
  long as a `:default`, `:fixed`, `:values` or `:required` is given.
  Attribute names are matched case-insensitively, and each attribute may
  only be configured once.

  If an attribute is added but neither the SVG file nor `:default` provides
  a value, `required: true` is added to the component attribute.

  An `aria-hidden` attribute is always added, and can be configured like
  any other attribute. Without configuration, the value of the SVG file is
  kept, or `"true"` is used if it does not have the attribute.

  The default value is `[]`.

---

*Consult [api-reference.md](api-reference.md) for complete listing*